开始之前

在开始讨论Aiursoft的相关服务API之前,请务必阅读此内容。这里将会详细介绍一些宏观参数。

基础API形式

Aiursoft全部各项微服务体系均采用下列两种API进行通讯:

  • HTTP
  • WebSocket

其中,Aiursoft的HTTP协议具有下列特点:

  • 所有服务直接完整对互联网公开
  • 所有通信强制使用HTTPS
  • 所有通信支持HTTP/2
  • 所有接口返回值类型均为Json
  • 所有接口返回值编码均为utf-8
  • 所有接口返回值均为英文
  • 所有接口请求的参数编码都为x-www-form-urlencoded

Aiursoft所有HTTP通讯的返回值中,都具有两个参数,也就是codemessage。例如:

{
    "code": 0,
    "message": "You have successfully created a message at channel:2!"
}

其中,code代表错误码,message代表基本提示信息。

在不同情况下,返回值的形态、结构可能会发生变化。但是都会包含这两个属性。因此建议开发者在任何情况下都应当优先检查code,仅在code符合期待后再进行下一步操作。若code是不期待的返回值,则应当进行处理,并在日志中记录message的值。

示例API

检查更新

请求地址:

https://api.aiursoft.com/

方法

HTTP GET

接口说明:

本接口可以检查当前用户状态、服务器时钟、显示语言。

返回值示例:

{
    "serverTime": "2018-03-12T10:29:31.2865921+08:00",
    "signedin": true,
    "local": "en",
    "user": {
        "id": "a75dff34-35d0-451d-bae3-af3c206bbc6b",
        "email": "anduin@aiursoft.com",
        "emailConfirmed": false,
        "bio": null,
        "nickName": "Anduin Xue",
        "sex": null,
        "headImgUrl": "https://oss.aiursoft.com/UsersIcon/9XNNIJF9RB.jpg",
        "preferedLanguage": "en",
        "accountCreateTime": "2018-02-09T15:09:23.1468265"
    },
    "code": 0,
    "message": "Server started successfully!"
}

常见错误分析

错误代码 错误说明 解决方案
0 成功完成了请求 不需要进行修正
-1 密钥错误 检查是否传入了合法的密钥
-2 请求被挂起 已经有一个相同意义的操作正在执行。请稍后再试。
-3 需要注意的警告 操作已经完成但是仍然需要注意。请阅读message参数值
-4 未找到 操作的目标对象不存在。请确认目标存在
-5 服务器崩溃 服务器未知错误。请向服务器团队提交反馈
-6 已经执行过了 已经有一个相同意义的操作已经执行完成。不需要进一步解决。
-7 没有足够的资源 目前可提供的资源无法满足操作。请检查请求的合理性。
-8 未授权 用户无法通过认证或没有进行该操作的权限。请确保用户的权限正常。
-10 输入值类型不符合规范 缺少参数,或传入的参数不符合规范。检查参数。
-11 超时 请求在处理中等待了很久而无法得到响应。请向服务器团队提交反馈。