接口调用约定

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

接口地址

希悦开放平台使用 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）等，这种类型的错误信息一般比较简单，我们统一使用如下数据结构表示错误：

验证型错误

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

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

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

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

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

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