Skip to content

RESTful API

Jump to bottom Edit New page
李文富 edited this page Mar 12, 2020 · 8 revisions

Table of Contents

REST

  • API 上的资源建议都采用 uuid 做为唯一标识
  • 对于超长（1K）的 GET URL，可以采用 POST 来代替
  • 版本，使用 URL 形式 {http_method} /{version}/{resources}...，如 GET /v0.3/products/01234567-89ab-cdef-0123-456789abcdef
  • 非标准 HTTP Verb，采用 POST /{resources}/{resource_id}/actions/{action} 的方式
  • CRUDL（create/retrieve/update/delete/list）中 L 的方案参考 OData，接口返回的是数组数据，必须返回以下结构，即使用一个具备有 items 属性的对象进行包裹
<syntaxhighlight lang="JavaScript"> { "items": [], "count": 20 } </syntaxhighlight>

Resource URL

  • Resource URL（最后一个单词为单数小写，表示用途归类）
  • 仅用来表示资源的路径（不应包括业务参数），及一些特殊的actions
  • 以复数（名词）进行命名，不管返回单个或多个资源
  • 使用小写、数字及下划线（下划线用来区分多个单词，为了与 JSON 对象及属性的命名方案保存一致不使用连字符“-”）
  • 资源的路径从根到子依次如下 /{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property} 如 GET /databases/{id}/name
  • 当 resource 的仅仅用于归类用途时，而不是具体的资源或层级关系，应该使用小写和单数。如 /user/

DTO

  • 资源都建议使用 uuid 作为唯一的标识，使用 8-4-4-4-12 的格式小写 uuid，命名为 id
  • JSON 中的 json-name 采用小写、数字及下划线进行命名，如 access_token
  • 日期，建议采用 ISO-8601 的规范，如（1994-11-05T13:15:30Z） ，在一些场合下也可以采用 Unix time

VERBS(CRUDL)

POST(C)

  • 创建资源
  • 执行资源的 actions
  • 超长的 GET 请求

GET(R)

  • 获取资源
  • 查询资源（列表、分页）

PUT/PATCH(U)

  • 更新资源（可以使用 PATCH 来标识局部更新，如果不支持，可以使用 X-HTTP-Method-Override: PATCH），PUT 与 PATCH 区别参考 PUT/PATCH

DELETE(D)

  • 删除资源

状态码 HTTP_STATUS_CODE

  1. 属于临时响应请求，通常表示请求已被接受，但还需要继续处理 // 1xx Informational
  2. 属于成功的请求 // 2xx Success
  3. 属于转向或通知请求 // 3xx Redirection
  4. 属于客户端请求有误 // --- 4xx Client Error ---
  5. 属于服务器错误 // --- 5xx Server Error ---

认证与授权

  • 待续

查询(L)方案

URI 的结构

  • 为了区分与业务的参数进行区分，所有的 query options 使用 $ 开头

query options

$filter

  • $filter 相当于 SQL 中的 where，语法为 filter={field} {operate} {value}，如 name eq 'myname'
  • 运算符优先级，较高位置的运算符 "与其他运算符相比，将更紧密地绑定到其操作数"。例如，and 的优先级高于 or，比较运算符的优先级高于其中任何一个运算符
组 运算符
逻辑运算符 not
比较运算符 eq、ne、gt、lt、ge、le
逻辑运算符 and
逻辑运算符 or
  • 基于性能及实现的考虑, 不支持 ne 不等于, 仅支持单个字段的条件查询

$orderby

  • 排序，语法为 orderby={field} [asc|desc]
  • 仅支持单个字段的排序
  • {field} 为查询资源的字段名称 [asc|desc] 排序的方向，默认为 asc

$select

  • 确定在查询结果集中返回每个文档的哪些字段
  • $Select参数分为两种形式：
    1. 单个星号（*），指示应返回所有可检索字段，或
    2. 以逗号分隔的字段路径列表，用于标识应返回哪些字段。
  • 如果您在未显式指定其子字段的情况下列出了复杂字段，则所有可检索的子字段都将包含在查询结果集中。

$offset

  • 分页参数，指示记录起始位置，默认 0

$limit

  • 分页参数，指示页大小，默认 10

$count

  • 是否返回总计数，默认 false，不返回

返回结果

仅返回数据

<syntaxhighlight lang="JavaScript"> { "items": [] } </syntaxhighlight>

返回数据与总条数

  • 请求参数 $count=true
<syntaxhighlight lang="JavaScript"> { "items": [], "count": 20 } </syntaxhighlight>

仅返回总条数

  • 接口功能为计数接口，否则不提供选项
<syntaxhighlight lang="JavaScript"> { "count": 20 } </syntaxhighlight>

通用错误码

HTTP_CODE STATUS_CODE CODE MESSAGE 备注
BAD_REQUEST 400 BIZ_CODE/INVALID_ARGUMENT 参数XX缺失 客户端请求错误, 不提示给用户

错误对象

  • 当接口出现非 2xx 的 HTTP（2xx时候，不能返回错误类型）响应时，采用返回统一 HTTP 响应信息
<syntaxhighlight lang="JavaScript"> HTTP/1.1 400 BAD REQUEST Content-Type: application/json { "code": "APP/INVALID_ARGUMENT", "message": "{error message}", "request_id": "a2888e60-83a9-4575-878e-3a0df752e7e2", "host_id": "{server identity}", "server_time": "2019-10-31T11:47:49.872+08:00" } </syntaxhighlight>
  • 错误规范使用三层信息：http status code、code、message

错误对象说明

  • 错误对象字段说明
    • http status code：符合 HTTP 协议的响应状态码
    • code：用来表示某类的错误，如缺少参数、类型不匹配等等，用来对 http status code 进行扩展，开发人员可以据此进行错误的细节处理
    • message：为错误的摘要信息，并且应该包含对用户处理该错误有指导意义的信息
    • request_id：错误的 uuid，用于帮助技术人员在日志系统中获得错误的详细
    • host_id：为发生错误的服务器
    • server_time：为发生错误时的服务器时间
  • code 命名规范
    • 采用大写字母单词命名，单词与单词之间用下划线（_）加以分割
    • 采用 {biz_name}/{error_code} 的命名结构， 其中 {biz_name} 为业务名称的缩写（可选），如 IM 等。UC/SERVICE_NOT_AVAILABLE
  • code 定义与使用规则
    • code 应以错误类别来定义，而非具体的某错误
    • code 要能准确标识错误，因为业务需要依赖此进行二次开发
    • 使用系统已经定义好的错误 code，见 #系统错误 code
    • 当错误发生在某个系统上，应该加上 {biz_name}/ 前缀，如 APP、USER 等等，见 BIZ_NAME

BIZ_NAME

BIZ_NAME 业务名 备注
USER 用户服务 用户账号、用户信息等
APP 应用服务 移动 Hybrid 应用服务
Add a custom footer
Add a custom sidebar

Clone this wiki locally