返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范：

• GET /collections：返回资源对象的列表（数组）

• GET /collections/identity：返回单个资源对象

• POST /collections：返回新生成的资源对象

• PUT /collections/identity：返回完整的资源对象

• PATCH /collections/identity：返回被修改的属性

• DELETE /collections/identity：返回一个空文档
  

错误处理

如果状态码是 4xx 或者 5xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可

{
    “error'”: “参数错误”
}

状态码

服务器向用户返回的状态码和提示信息，使用标准 HTTP 状态码。

• 200 OK 服务器成功返回用户请求的数据，该操作是幂等的。

• 201 CREATED 新建或修改数据成功。

• 204 NO CONTENT 删除数据成功。

• 400 BAD REQUEST 用户发出的请求有错误，该操作是幂等的。

• 401 Unauthorized 表示用户没有认证，无法进行当前操作。

• 403 Forbidden 表示用户访问是被禁止的。

• 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。

• 500 INTERNAL SERVER ERROR 服务器发生错误，用户将无法判断发出的请求是否成功。

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。

举例

• ?offset=10：指定返回记录的开始位置。

• ?page=2&per_page=100：指定第几页，以及每页的记录数。

• ?sortby=name&order=asc：指定返回结果排序，以及排序顺序。
  

• ?animal_type_id=1：指定筛选条件

HTTP 动词

对于资源的操作（CURD），由 HTTP 动词（谓词）表示。

• GET：从服务器取出资源（一项或多项）。

• POST：在服务器新建一个资源。

• PUT：在服务器更新资源（客户端提供改变后的完整资源）

• PATCH：在服务器更新资源（客户端提供改变的属性）。

• DELETE：从服务器删除资源。

举例

• POST /zoos：新建一个动物园

• GET /zoos/ID：获取某个指定动物园的信息

• PUT /zoos/ID：更新某个指定动物园的信息

• DELETE /zoos/ID：删除某个动物园

资源路径

在 RESTful 架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说 API 中的名词应该使用复数。

举例

举例来说，有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos //动物园资源

https://api.example.com/v1/animals //动物资源

https://api.example.com/v1/employees //雇员资源

如何设计 RESTful API

• 资源路径（URI）

• HTTP 动词

• 过滤信息

• 状态码

• 错误处理

• 返回结果
  

如何设计RESTful API

设计资源路径：网址代表一种资源，网址中不能出现动词，只能有名词，一般来说名词应该使用复数。

 restful api 状态吗

 restful api 状态吗

restful api 状态码

返回结果规范2

返回结果规范1

错误处理 键值

状态吗，使用标准http状态码3

状态吗，使用标准http状态码

状态吗，使用标准http状态码

过滤信息例子

过滤信息1

http 动词例子

http动词

资源路径举例

资源路径

在restful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数

如何设计restful API

资源路径 URI

HTTP动词

过滤信息

状态码

错误处理

返回结果

返 回 结 果 2

返 回 结 果

错 误 处 理

状 态 码 3

状 态 码 2

状 态 码