EduSoho企培开发指南

Appearance

REST API ​

版本 ​

版本控制

​

新API路由和老API路由都是相同的路由前缀。如果在header里增加Accept参数，值为application/vnd.edusoho.v2+json，将会访问新接口。如果不加，默认访问老接口。

排序 ​

一些接口提供对结果排序，在请求URL上使用sort参数即可，这个参数使用逗号分隔多个排序字段，默认排序是按照创建时间倒序

field表示按照field字段正排 -field表示按照field字段倒排

比如说,要获取学员最多，并且点击量最多的课程:

GET /course_sets?sort=-studentNum,-hitNum

响应 ​

服务器端API程序能返回的响应，HTTP状态码均应为200。非200的请求，均为异常请求，比如：API服务器宕机、服务内部错误、网络异常等。

成功响应 ​

单个资源的获取、创建、更新，应响应完整的资源结构体，比如创建或更新一个用户后应返回完整的用户结构体

json
{
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "createdTime": "2016-09-21T00:27:47+08:00"
}

资源结构体中的key的命名采用驼峰规则

如果某个key表示时间，那么应返回ISO 8601格式标准的时间

获取多个资源的请求，有分页的应响应如下结构体，我们称此类结构为pagedlist

json
{
    "data": [
        {"key1": "value1", "key2": "value2"},
        {"key1": "value1", "key2": "value2"},
        {"key1": "value1", "key2": "value2"}
    ],
    "paging": {
        "total": 100,
        "offset": 50,
        "limit": 10
    }
}

total表示总共有多少个资源，offset表示本次响应返回的结果集是从第几个资源起的序号，limit表次本次响应返回的结果集最大个行数。

无分页的应响应如下结构体，我们称此类结构为list

json
[
    {"key1": "value1", "key2": "value2"},
    {"key1": "value1", "key2": "value2"},
    {"key1": "value1", "key2": "value2"}
]

失败响应 ​

API请求操作失败应返回如下的结构体，我们称此类结构体为Error结构体

json
{
    "error": {
        "message" : "错误描述信息。",
        "code": "错误码（值为整形）"
    }
}

错误码有

CodeTypeDescriptionHTTP Code
1API_NOT_FOUNDAPI不存在404
2BAD_REQUEST请求报文格式不正确：
1.请求体非json格式
2.未设置application/json头部		400
3API_TOO_MANY_CALLSAPI访问次数过多429
4INVALID_CREDENTIALCredential不正确:
1.Credential格式不正确 2. Credential签名不正确		401
5EXPIRED_CREDENTIALCredential已过期401
6BANNED_CREDENTIALCredential对应的用户被禁止401
7INTERNAL_SERVER_ERROR服务内部错误，需联系管理员500
8SERVICE_UNAVAILABLE服务暂时下线，请稍后重试:
1.升级维护中
2.过载保护中
3.内部服务处理超时		503
9INVALID_ARGUMENT参数缺失、参数不正确400
10RESOURCE_NOT_FOUND访问的资源不存在404
11UNAUTHORIZED用户没有被认证401
12METHOD_NOT_ALLOWED请求方法不被允许405

封装 ​

如果你的 API 客户端访问 HTTP 状态码和 HTTP 头比较困难, 你可以在 url 上加一个 envelope=true 的参数, 这样做的了之后， HTTP 状态码都是 200 的，并且所有返回信息都会封装成一个对象返回。

GET /api/users/does-not-exist?envelope=true

{
  "status": 404,
  "headers": {
  },
  "response": {
    "error": {
      "message": "API Resource Not found",
      "code": 2
    }
  }
}