接口调用约定

希悦开放平台遵循 RESTFul API 设计规范,本节简述调用本开放平台 API 的一些约定,以便开发者能够更方便的入手和使用。

接口地址

OAuth的ClientId也区分生产环境和测试环境,请先确认适用于哪个环境。

常用状态码

希悦开放平台使用 HTTP Status Code 表示请求状态信息,标识请求是否成功处理,如果失败,返回详细的失败原因。下面是常用的状态码及含义:

状态码 使用说明
200 请求处理成功,一切正常
201 资源被成功创建,用于 POST 请求
204 请求处理成功,但没有返回结果,比如 DELETE 请求
400 错误的请求,比如 client 提供了错误的 json 数据,或者不正确的查询参数(query parameters)
401 授权失败,没有提供 Authorization Header,或者 Token 失效
403 无权限请求特定的资源
404 请求的资源不存在
422 数据验证失败,一般用于 POST, PUT, PATCH 修改数据的时候
500 服务器内部错误

错误信息

为了让错误更容易处理,我们制定了标准的错误数据格式,保持数据结构一致性。错误有为两种类型,一般型错误和验证型错误。

一般型错误

一般用于 HTTP 状态码为非 422 时,比如请求参数错误(400),未授权(403)等,这种类型的错误信息一般比较简单,我们统一使用如下数据结构表示错误:

字段名称 字段简介
name 错误的名称或类别
code 错误状态码
message 错误的详细消息

验证型错误

一般用于 HTTP 状态码为 422 时,发生的场景是数据验证失败需要返回错误信息(比如表单提交)时。这种类型的错误信息一般比较复杂,也存在需要同时返回多个错误的情况。为此,此类错误将返回数组,数组的每个元素包含错误的具体信息,其结构如下:

字段名称 字段简介
field 发生错误的字段,用于标识错误发生的地方
message 具体发生的一个错误原因

分页控制

对于集合类型的 API,我们通过 URI 参数进行分页控制,这些参数如下:

参数名称 参数简介
$per-page 每页返回的结果数量,该参数应该为 int 类型
$page 指定 API 返回某一页的数据,该参数应该为 int 类型, 默认为 1
$paginated 控制是否分页,取值为 bool,可以能够接收 0, 1, true, false 作为参数

然后,我们通过 HTTP Header 返回分页的一些信息,比如集合总数,总分页数等,这些 Header 只有在启用分页时可用,具体如下表:

参数名称 参数简介
X-Pagination-Current-Page 当前数据所处的页数
X-Pagination-Page-Count 当前查询数据的总页数
X-Pagination-Per-Page 当前查询数据每页的数量
X-Pagination-Total-Count 当前查询数据的总行数

语言设定

我们通过 Accept-Language 指定客户端接收的语言,对于不方便指定 Header 的 HTTP Client,也可以通过 $lang Query 参数指定,如果两个地方都指定了,以 Header 为准。

results matching ""

    No results matching ""