RESTful API 设计总结

@(技术-架构)[API, 规范, 设计]

RESTful的接口设计风格应用的越来越广泛，包括Spring Cloud等微服务架构平台之间的调用都是以RESTful设计风格为主，但是很多程序猿依然是停留在表面的理解上，没有深刻的去理解使用RESTful风格规范，同时在设计RESTful接口的时候是有很多细节需要思考，以下就是个人对RESTful接口的深入理解以及总结。

1、协议&域名&版本

协议：API与用户的通信协议，总是使用HTTPS协议。
域名：可以部署专有域名或者是主域名下加入URL里面。

https://api.github.com
https://github.com/api

版本：应该将API的版本号放入URL。

https://github.com/v1

2、CURD的请求设计

REST的关键原则把API分解成一种逻辑上的资源。这些资源可以通过有具体含义的HTTP方法（GET, POST, PUT, PATCH, DELETE）来进行修改。

GET /users - 获取user列表
GET /users/12 - 获取指定ID为12的user对象
POST /users - 创建一个新的user
PUT /users/12 - 更新id为12的user
PATCH /users/12 - 对id为12的user进行部分更新
DELETE /users/12 - 删除id为12的user

① 新增：新增对象一般用到的是POST方法。

POST /users - 创建一个新的user
POST /users?count=4 - 批量创建user对象

② 删除：DELETE作为删除的方法

DELETE /users/12 - 删除id为12的user
DELETE /users [134 , 232 , 223 , 442] - 批量删除id为134 , 232 , 223 , 442的user

③ 更新：PUT、PATCH都是作为更新的HTTP方法，PUT表示更新USER对象，PATCH是对对象部分更新

PUT /users/12 - 更新id为12的user
PUT /users - 批量更新user
PATCH /users/12 - 对id为12的user进行部分更新
PATCH /users - 批量对user进行部分更新

④ 查询：GET一般作为查询的HTTP方法，如何优雅的满足复杂的接口，不是一件很值得探讨的事情。
查询单个对象

GET /users/12 - 获取指定ID为12的user对象

查询多个对象

GET /users - 获取user列表

条件过滤与分页查询

GET /users?page=3&page_count=30：指定第几页，以及每页的记录数。
GET /users?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
GET /users?role_id=1：指定筛选条件

查询多个对象时，一般返回对象的列表，当分页查询需要返回查询的总的数据，应当在响应头部里面加入X-Total-Count的参数，同时在头部加入X-Page和X-Page-Size参数。

X-Total-Count：1023
X-Page：3
X-Page-Size：30

复杂的查询条件当我们使用高级搜索的时候，GET方法的参数长度是没法满足查询的需求，这时候我们可以用POST方法提交参数实体来实现需求。

POST /users/search?page=3&page_count=30
{
name : admin ,
phone : 124 ,
sex : 1
}

过滤返回对象属性

GET /users/12?fields=id,name,phone - 设置返回对象的属性

3、返回结果设计

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

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
POST /collection：（批量新增）返回新生成的资源对象数量
PUT /collection/resource：返回完整的资源对象
PUT /collection：（批量更新）返回完整的资源对象数量
PATCH /collection/resource：返回完整的资源对象
PATCH /collection：（批量更新）返回完整的资源对象数量
DELETE /collection/resource：返回一个空文档
DELETE /collection：（批量删除）返回完整的资源对象数量

状态码

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。>
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

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

{
error: "Invalid API key"
}

4、Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
比如，当用户向api.github.com的根目录发出请求，会得到这样一个文档。

{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}

从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。

{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}

上面代码表示，服务器给出了提示信息，以及文档的网址。

原文地址：https://segmentfault.com/a/1190000011338151