Skip to main content

Restful 接口规格

本章将给出用于数据交换（Request + Response）的文档规格。文档遵循 JSON RFC7159 格式。

请求（Request）#

组成要素#

要素描述
HTTP 方法GET：获取资源
POST：创建资源、向资源提交数据进行处理
PUT：整体更新资源，即整体替换，如更新密码
PATCH：部分更新资源，即差分更新（Merge），如更新用户信息
DELETE： 删除资源
API 服务 URL提供服务的 URL ，如：http://api.somesite.com
资源 URI查询、创建、更新、删除的资源 URI ，如：/tenants/{tenantId}/orders
查询参数（Query Parameters）用于过滤、限制大小、排序返回结果的参数
HTTP 请求头（Request Header）包含授权等信息
JSON 请求体POST、PUT、PATCH 请求所需的数据

URI 命名规范#

为了保证请求能正确到达服务端，URI需遵循以下命名规范：

  • 名称只能包含下列字符，不能包含保留字符以及不安全字符：
U+0061 to U+007A, “a-z”
U+0030 to U+0039, “0-9”
U+002D HYPHEN-MINUS, “-“

保留字符是指在URL中具有特定意义的字符。不安全字符是指那些在URL中没有特殊含义，但在URL所在的上下文中可能具有特殊意义的字符。

  • 名称中英文字母全部采用小写
  • 名称不能以 “-“ 开头

URI示例：

获取订单列表
GET /tenants/{tenantId}/orders
重置密码
POST/users/{credential}/reset-password

查询参数（Query Qarameters）#

对于 REST GET 请求可以指定若干查询参数。这些参数用于指定过滤条件、限制数据数量和排序。

命名规范#

查询参数采用驼峰式命名，和程序中的变量风格保持一致。

过滤条件（filter）#

下面的GET请求用于返回指定日期内的创建的订单数据。

GET /tenants/{tenantId}/orders?createdAtFrom=2020-07-01&createdAtEnd=2020-07-31

限制数据数量和排序（limit size and sort）#

参数类型描述
page[no]或pageNointeger已取得记录列表中最后一条记录的 ID，用于取得更多记录
page[size] 或 pageSizeinteger一次取得的件数，即客户端一页显示的件数
sortBystring格式为 sortBy[field1]={oder1}&sortBy[field1]={oder1} 或
sortBy[0]=field1:oder1&sortBy[1]=field2:oder2
asc：升序；desc：降序

下面的GET请求用于返回最新20件订单数据

GET /tenants/{tenantId}/orders?page[no]=1&page[size]=20&sortBy[createdAt]=desc
或
GET /tenants/{tenantId}/orders?pageNo=1&pageSize=20&sortBy[0]=createdAt:desc

HTTP 请求头（Request Header）#

头描述
Accept客户端可接收的应答内容类型。
Accept: application/json
Authorization服务端配发的 JWT 令牌。
Authorization: Bearer <token>
Content-Type请求内容类型，服务端根据此类型解析请求数据。
Content-Type: application/json

应答（Response）#

应答内容包含 HTTP 状态码和 JSON 格式的有效载荷（payloads）两个部分。

请求成功#

对于请求成功将返回 2XX HTTP 状态码：

状态码描述
200 OK请求成功。
201 CreatedPOST 方法成功创建一个资源。如果该资源已经被创建返回 200 状态码。
202 Accepted服务端成功接收请求，请求将被延后处理。
204 No Content服务端成功执行请求，无返回值。

请求错误#

对于请求错误将返回 4XX 或 5XX HTTP 状态码：

状态码错误代码及描述原因
400 Bad RequestINVALID_REQUEST
请求格式、语法不正确或未通过输入数据校验		可能的原因如下：
  • 数据不符合预期格式
  • 缺少必要的元素
  • 未通过输入数据校验
    • 401 UnauthorizedAUTHENTICATION_FAILURE
    认证（Authentication）失败，无效的凭证（credentials）    		请求需要认证，调用者未提供有效凭证
    403 ForbiddenNOT_AUTHORIZED
    授权（Authorization）失败，没有足够权限    		尽管调用者提供了有效的凭证，但没有被授权访问本资源
    404 Not FoundRESOURCE_NOT_FOUND
    指定的资源不存在    		请求的 URI 不正确或 URI 对应的资源不存在。
    如：数据中没有和指定主键匹配的数据。
    405 Method Not AllowedMETHOD_NOT_SUPPORTED
    服务端没有实现请求的 HTTP 方法    		服务不支持请求的 HTTP 方法
    406 Not AcceptableMEDIA_TYPE_NOT_ACCEPTABLE
    服务端没有实现客户端可接受的媒体类型    		服务端不能用客户端请求的媒体类型返回答应。
    如客户端发送可接收 application/xml，服务端却只能生成 application/json 的应答
    415 Unsupported Media TypeUNSUPPORTED_MEDIA_TYPE
    服务端不支持请求中有效载荷的媒体类型    		服务端不能处理请求中有效载荷的媒体类型。如客户端发送 application/xml 类型请求，服务端只接收 application/json 媒体类型
    429 Unprocessable EntitRATE_LIMIT_REACHED
    到达API 限流值，阻塞请求    		API 请求达到了限流值
    500 Internal Server ErrorINTERNAL_SERVER_ERROR
    内部服务错误    		服务端发生了非预期的错误
    503 Service UnavailableSERVICE_UNAVAILABLE
    服务无效    		因临时维护服务端不能处理请求

    JSON 有效载荷结构#

    根元素必须是一个 JSON 对象，对象包含以下元素：

    名称类型必须说明
    success布尔必须返回结果成功标志，true 或 false。与 2XX HTTP状态码 一起使用作为成功标志
    error对象必须错误对象，data 和 error 不能同时出现
    data对象必须数据对象，data 和 error 不能同时出现

    error 对象：

    名称类型必须说明
    code字符串必须可读的唯一识别编码。例如： NOT_AUTHORIZED
    message字符串必须错误描述。例如：授权失败，没有足够权限
    fields数组可选校验错误中的多个错误的描述，通常含有 name 和 message 两个属性