RESTful API

一、概述

起源：REST，即Representational State Transfer的缩写，翻译为"表现层状态转化"。其中省略了主语，“表现层"其实指的是"资源”（Resources）的"表现层"。我们把"资源"具体呈现出来的形式，叫做它的"表现层"（Representation）。

RESTful AP 的设计是以资源为核心，每一个URI代表一种资源。【因此：URI不饱包含动词，只能是名称】

tip：为了与 json 对象及属性的命名方案保持一致API命名遵循如下规则

• API中只包含名词
• 无论资源是单个还是多个，API的名词都以复数命名
• API使用小写、数字、及下划线来区分多个单词

eg：资源的路径从根到子依次如下

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

当一些API很难完全用名称来构建路径是，可以引入active命名

eg：用户密码修改

【PUT】  /users/{user_id}/password/actions/modify

二、请求方式

1、GET 用于查询资源

2、POST 用于创建资源

3、PUT 用于更新服务端的资源的全部信息

4、PATCH 用于更新服务端的资源的部分信息

5、DELETE 用于删除服务端的资源。

eg：用户通过GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。

【GET】          /users                # 查询用户信息列表
【GET】          /users/1001           # 查看某个用户信息
【POST】         /users                # 新建用户信息
【PUT】          /users/1001           # 更新用户信息(全部字段)
【PATCH】        /users/1001           # 更新用户信息(部分字段)
【DELETE】       /users/1001           # 删除用户信息

三、查询参数

• 分页参数：offset+limit 结合实现分页查询【offset指定返回记录的开始位置、limit指定当前页的大小】

  【GET】  /{version}/{resources}/{resource_id}?offset=0&limit=20
  

• 字段排序：orderby实现单个字段排序

  【GET】  /{version}/{resources}/{resource_id}?orderby={field} [asc|desc]
  

• 是否支持count字段：count 表示返回数据是否包含总条数，它的默认值为 false。

  【GET】  /{version}/{resources}/{resource_id}?count=[true|false]
  

• 业务参数：offset、 limit、 orderby 是一些公共参数。此外，业务场景中还存在许多个性化的参数。

  【GET】  /v1/categorys/{category_id}/apps/{app_id}?enable=[1|0]&os_type={field}&device_ids={field,field,…}
  

四、状态码

实际开发过程中常用的一些状态码，以供参考。

状态码	描述
200	请求成功
201	创建成功
400	错误的请求
401	未验证
403	授权失败
404	无法找到
409	资源冲突
500	服务端内部错误

五、异常响应

当 RESTful API 接口出现非 xxx 的 HTTP 错误码响应时，采用全局的异常结构响应信息。

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "code": "INVALID_ARGUMENT",
    "message": "{error message}",
    "cause": "{cause message}",
    "request_id": "01234567-89ab-cdef-0123-456789abcdef",
    "host_id": "{server identity}",
    "server_time": "2014-01-01T12:00:00Z"
}

六、正常响应

• 单条数据：返回一个对象的 JSON 字符串。

  HTTP/1.1 200 OK
  {
      "id" : "01234567-89ab-cdef-0123-456789abcdef",
      "name" : "example",
      "created_time": 1496676420000,
      "updated_time": 1496676420000,
      ...
  }
  

• 列表数据：返回一个封装的结构体。

  HTTP/1.1 200 OK
  {
      "count":100,
      "items":[
          {
              "id" : "01234567-89ab-cdef-0123-456789abcdef",
              "name" : "example",
              "created_time": 1496676420000,
              "updated_time": 1496676420000,
              ...
          },
          ...
      ]
  }
  

七、案例

以“获取用户列表”为案例。

【GET】     /v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20] 获取用户列表
功能说明：获取用户列表
请求方式：GET
参数说明
- keyword: 模糊查找的关键字。[选填]
- enable: 启用状态[1-启用 2-禁用]。[选填]
- offset: 获取位置偏移，从 0 开始。[选填]
- limit: 每次获取返回的条数，缺省为 20 条，最大不超过 100。 [选填]
响应内容
HTTP/1.1 200 OK
{
    "count":100,
    "items":[
        {
            "id" : "01234567-89ab-cdef-0123-456789abcdef",
            "name" : "example",
            "created_time": 1496676420000,
            "updated_time": 1496676420000,
            ...
        },
        ...
    ]
}
失败响应
HTTP/1.1 403 UC/AUTH_DENIED
Content-Type: application/json
{
    "code": "INVALID_ARGUMENT",
    "message": "{error message}",
    "cause": "{cause message}",
    "request_id": "01234567-89ab-cdef-0123-456789abcdef",
    "host_id": "{server identity}",
    "server_time": "2014-01-01T12:00:00Z"
}
错误代码
- 403 UC/AUTH_DENIED    授权受限