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": "错误码(值为整形)"
    }
}

错误码有

Code Type Description HTTP Code
1 API_NOT_FOUND API不存在 404
2 BAD_REQUEST 请求报文格式不正确:
1.请求体非json格式
2.未设置application/json头部
400
3 API_TOO_MANY_CALLS API访问次数过多 429
4 INVALID_CREDENTIAL Credential不正确:
1.Credential格式不正确 2. Credential签名不正确
401
5 EXPIRED_CREDENTIAL Credential已过期 401
6 BANNED_CREDENTIAL Credential对应的用户被禁止 401
7 INTERNAL_SERVER_ERROR 服务内部错误,需联系管理员 500
8 SERVICE_UNAVAILABLE 服务暂时下线,请稍后重试:
1.升级维护中
2.过载保护中
3.内部服务处理超时
503
9 INVALID_ARGUMENT 参数缺失、参数不正确 400
10 RESOURCE_NOT_FOUND 访问的资源不存在 404
11 UNAUTHORIZED 用户没有被认证 401
12 METHOD_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
    }
  }
}

results matching ""

    No results matching ""