RESTful API 设计总结

RESTful API 设计总结

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

RESTful的接口设计风格应用的愈来愈普遍，包括Spring Cloud等微服务架构平台之间的调用都是以RESTful设计风格为主，可是不少程序猿依然是停留在表面的理解上，没有深入的去理解使用RESTful风格规范，同时在设计RESTful接口的时候是有不少细节须要思考，如下就是我的对RESTful接口的深刻理解以及总结。

---

一、协议&域名&版本

协议：API与用户的通讯协议，老是使用HTTPS协议。
域名：能够部署专有域名或者是主域名下加入URL里面。

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

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

https://github.com/v1

二、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 - 设置返回对象的属性

三、返回结果设计

针对不一样操做，服务器向用户返回的结果应该符合如下规范。

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"
}

四、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"
}

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