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服务器宕机、服务内部错误、网络异常等。

成功响应

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

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

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

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

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

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

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

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

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

失败响应

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

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

错误码有

封装

如果你的 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
    }
  }
}