API接口使用说明

基本使用

API请求应以 api API版本为前缀。

有效的API请求示例:

API旨在根据上下文和操作返回不同的状态代码。这样一来，如果一个请求导致错误，调用者就可以深入了解出了什么问题。

下表概述了API函数通常的行为。

请求类型	描述
`GET`	访问一个或多个资源并将返回。
`POST`	返回 `201 Created` 如果成功创建了资源，并返回新创建资源。
`GET` / `PUT`	`200 OK` 如果资源被成功访问或修改，则返回（修改）结果。
`DELETE`	`204 No Content` 如果资源被成功删除，则返回。

API设计为根据上下文返回不同的状态代码。这样，如果请求导致错误，调用者能够得到
洞察什么错误。

下表显示了API请求的可能返回代码。

返回值	描述
`200`	OK。一切正常。
`201`	响应 `POST` 请求时成功创建一个资源。`Location` header 包含的URL指向新创建的资源。
`204`	该请求被成功处理，响应不包含正文内容 (类似 `DELETE` 请求)。
`304`	资源没有被修改。可以使用缓存的版本。
`400`	错误的请求。可能通过用户方面的多种原因引起的，例如在请求体内有无效的数据或无效的操作参数，等等。
`401`	验证失败，需要有效的用户令牌。
`403`	已经经过身份验证的用户不允许访问指定的 API 末端。
`404`	所请求的资源不存在。
`405`	不被允许的方法。
`415`	不支持的媒体类型。所请求的内容类型或版本号是无效的。
`422`	数据验证失败 (例如，响应一个 `POST` 请求)。请检查响应体内详细的错误消息。
`429`	请求过多。由于限速请求被拒绝。
`500`	内部服务器错误。这可能是由于内部程序错误引起的。

为了确保我们能知道访问者是谁，API 要求必须传递 User-Agent Header，否则将会拒绝请求。
例如：

有时，返回的结果将跨越多个页面。列出资源时，您可以传递以下参数:

参数	描述
`page`	页码 (默认: `1`)
`per_page`	每页列出的项目数 (默认: `15`, 最大: `100`)

下面的事例中, 我们每个页面列出 50 个用户。

区间查询遵循左闭右开原则，即开始区间包括区间开始的值，但不包括区间结束的值。如果开始值和结束值相同，则为无效区间，函数直接返回错误。

当您尝试访问不存在的API网址时，您将收到 404 Not Found 。

HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "message": "Object not found: 1213"
}