[RESTful] 设计要素

如何设计RESTful API

• 资源路径（入何规划资源路径）
• HTTP动词（请求方式 GET/POST...）
• 过滤信息（分页，查询操作的时候进行信息过滤）
• 状态码（服务器端响应什么样的状态码）
• 错误处理（如果传入服务器端的参数有问题）
• 返回结果（不同请求的返回结果）

资源路径

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

　　例如：有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，它的路径应该设计成：　　

https://api.example.com/v1/zoos    //动物园资源
https://api.example.com/v1/animals　　//动物资源
https://api.example.com/v1/employees　　//雇员资源

　　https：协议头。v1：关于API的版本号（还可以加到HTTP请求头中）。zoos：动物园资源（复数）。

　　动物园只有一个，所以没有指明动物园的ID。

HTTP动词

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

• GET：从服务器取出资源（一项或多项）
• POST：在服务器新建一个资源
• PUT：在服务器更新资源（客户端提供改变后的完整资源）
• DELETE：从服务器删除资源
• PATCH：在服务器更新资源（客户端提供改变的属性）。

　　put更新资源后，服务器端会返回整个资源。而patch更新完之后只会返回跟新的属性。

　　举例：

POST/zoos    //新建一个动物园
GET/zoos/ID　　//获取某个指定动物园的信息
PUT/zoos/ID　　//更新某个指定动物园的信息
DELETE/zoos/ID　　//删除某个动物园

过滤信息

　　如果记录数量很多，服务器不可能都将他们返回给用户。

　　API应该提供参数，过滤返回结果。

　　举例：

?offset=10    //指定返回记录的开始位置
?page-2&per_page=100　　//指定第几页，以及每页的记录数
?sortby=name&order=asc　　//指定返回结果排序，以及排序顺序
?animal_type_id=1　　//指定筛选条件

　

状态码

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

• 200 OK ：服务器成功返回用户请求的数据，该操作是幂等的
• 201 CREATED ：新建或修改数据成功
• 204 NO CONTENT ：删除数据成功
• 400 BAD REQUEST ：用户发出的请求有错误，该操作是幂等的
• 401 Unauthorized ：表示用户没有认证，无法进行当前操作
• 403 Forbidden ：表示用户访问时被禁止的
• 422 Unprocesable Entity ：当创建一个对象时，发生一个验证错误
• 500 INTERNAL SERVER ERROR ：服务器发生错误，用户将无法判断发出的请求是否成功

错误处理

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

{
        "error" : "参数错误"
}

返回结果

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

• GET/collections ：返回资源对象的列表（数组）
• GET/collections/identity ：返回单个资源对象（指定的标识符（identity）对应的对象，不存在返回404状态码）
• POST/collections ：返回新生成的资源对象（创建对象的时候）
• PUT/collections/identity ：返回完整的资源对象
• PATCH/collections/identity ：返回被修改的属性
• DELETE/collections/identity ：返回一个空文档