RESTful API（2018-5-8整理）
METHOD
GET:MDN 解释
请求指定的资源。使用?GET?的请求应该只用于获取数据。
示例：
GET /api/example/
GET /api/example/:id(\\d+)/
------------------------------------------------------------------------------------------------------------------
POSTMDN解释
给指定资源新增内容。使用POST的请求建议仅用户新增数据。
请求主体：
1.application/x-www-form-urlencoded: 数据被编码成以 '&' 分隔的键-值对, 同时以 '=' 分隔键和值. 非字母或数字的字符会被?percent encoded: 这也就是为什么这种类型不支持二进制数据的原因 (应使用?multipart/form-data?代替).
2.multipart/form-data
3.text/plain
示例：
POST /api/example/
----------------------------------------------------------------------------------------------------------------
DELETEMDN解释
用于删除指定的资源。
响应：
1.状态码 ?202?(Accepted) 表示请求的操作可能会成功执行，但是尚未开始执行。
2.状态码?204?(No Content) 表示操作已执行，但是无进一步的相关信息。
3.状态码 ?200?(OK) 表示操作已执行，并且响应中提供了相关状态的描述信息。
示例：
DELETE /api/example/1
DELETE /api/example?id=1,2,3
?
----------------------------------------------------------------------------------------------------------------
?
PUTMDN解释
用于新增资源或者使用请求中的有效负载替换目标资源的表现形式。
响应：
1.如果目标资源不存在，并且PUT方法成功创建了一份，那么源头服务器必须返回201?(Created) 来通知客户端资源已创建。
2.如果目标资源已经存在，并且依照请求中封装的表现形式成功进行了更新，那么，源头服务器必须返回200?(OK) 或者204?(No Content) 来表示请求的成功完成。
示例
PUT /api/example/1
?
----------------------------------------------------------------------------------------------------------------
?
PATCHMDN解释
在HTTP协议中，请求方法?PATCH??用于对资源进行部分修改。
请求主体
1.使用默认的?application/x-www-form-urlencoded?做为 content type 的简单表单:
2.使用?multipart/form-data?作为 content type 的表单:
?
示例
PATCH /api/example/1
?
?----------------------------------------------------------------------------------------------------------------
?
关于返回
?
?
?
----------------------------------------------------------------------------------------------------------------
?
序列化和反序列化
?
序列化和反序列化是RESTful API开发中的一项硬需求，所以几乎每一种常用的开发语言都会有一个或多个优秀的开源库，来实现序列化和反序列化，因此，我们在开发RESTful API时，没必要制造重复的轮子，选一个好用的库即可,$.AJAX AXIOS FLY都可以！其他的语言的可以去git下（如 python中的marshmallow）。
?
----------------------------------------------------------------------------------------------------------------
?
?
数据校验
?
当客户端向服务器发出post,?put或patch请求时，通常会同时给服务器发送json格式的相关数据，服务器在做数据处理之前，先做数据校验，是最合理和安全的前后端交互。如果客户端发送的数据不正确或不合理，服务器端经过校验后直接向客户端返回400错误及相应的数据错误信息即可。常见的数据校验包括：
?
?
----------------------------------------------------------------------------------------------------------------
?
Authentication 和 Permission
?
常用的认证机制是Basic Auth和OAuth，RESTful API 开发中，除非API非常简单，且没有潜在的安全性问题，否则，认证机制是必须实现的，并应用到API中去。Basic Auth非常简单，很多框架都集成了Basic Auth的实现，自己写一个也能很快搞定，OAuth目前已经成为企业级服务的标配，其相关的开源实现方案非常丰富。如：jsonwebtoken.js 等等
?
----------------------------------------------------------------------------------------------------------------
?
CORS
?
懒 难求的打字?自己跳过去看
?
node express CORS配置
?
----------------------------------------------------------------------------------------------------------------
?
?
URL 规范
?
其命名和结构需要有意义。因此，在设计和编写URL时，要符合一些规范。
?
1. API 版本控制
?
规范的API应该包含版本信息，在RESTful API中，最简单的包含版本的方法是将版本信息放到url中，如：
?
2.URL应指向资源
?
URL应指向资源，而不是规定动作，动作由METHOD来决定
3.GET 和HEAD必须安全
贼吉尔恐怖的一个案例
4.使用?nested routing来获取一个资源子集
如果语义上将资源子集看作一个独立的资源集合，则使用?nested routing?感觉更恰当，如果资源子集的获取是出于过滤的目的，则使用filter更恰当。
?
5.Filter
对于资源集合，可以通过URLSearchParams对资源进行过滤
?
?
?
?
GET:MDN 解释
请求指定的资源。使用?GET?的请求应该只用于获取数据。
请求是否有主体 否
成功的响应是否有主体 是
安全 是
幂等 是
可缓存 是
HTML 表单是否支持 是
示例：
GET /api/example/
GET /api/example/:id(\\d+)/
------------------------------------------------------------------------------------------------------------------
POSTMDN解释
给指定资源新增内容。使用POST的请求建议仅用户新增数据。
请求是否有主体 是
成功的响应是否有主体 是
安全 否
幂等 否
可缓存 仅缓存最近的数据
HTML 表单是否支持 是
请求主体：
1.application/x-www-form-urlencoded: 数据被编码成以 '&' 分隔的键-值对, 同时以 '=' 分隔键和值. 非字母或数字的字符会被?percent encoded: 这也就是为什么这种类型不支持二进制数据的原因 (应使用?multipart/form-data?代替).
2.multipart/form-data
3.text/plain
示例：
POST /api/example/
----------------------------------------------------------------------------------------------------------------
DELETEMDN解释
用于删除指定的资源。
请求是否有主体 否
成功的响应是否有主体 否
安全 否
幂等 是
可缓存 否
HTML 表单是否支持 否
响应：
1.状态码 ?202?(Accepted) 表示请求的操作可能会成功执行，但是尚未开始执行。
2.状态码?204?(No Content) 表示操作已执行，但是无进一步的相关信息。
3.状态码 ?200?(OK) 表示操作已执行，并且响应中提供了相关状态的描述信息。
示例：
DELETE /api/example/1
DELETE /api/example?id=1,2,3
?
----------------------------------------------------------------------------------------------------------------
?
PUTMDN解释
用于新增资源或者使用请求中的有效负载替换目标资源的表现形式。
请求是否有主体 是?
成功的响应是否有主体 否
安全 否
幂等 是
可缓存 否
HTML 表单是否支持 否
- PUT与POST方法的区别在于，PUT方法是幂等的：调用一次与连续调用多次是等价的（即没有副作用），而连续调用多次POST方法可能会有副作用，比如将一个订单重复提交多次。
- PUT 用于整体覆盖
响应：
1.如果目标资源不存在，并且PUT方法成功创建了一份，那么源头服务器必须返回201?(Created) 来通知客户端资源已创建。
2.如果目标资源已经存在，并且依照请求中封装的表现形式成功进行了更新，那么，源头服务器必须返回200?(OK) 或者204?(No Content) 来表示请求的成功完成。
示例
PUT /api/example/1
?
----------------------------------------------------------------------------------------------------------------
?
PATCHMDN解释
在HTTP协议中，请求方法?PATCH??用于对资源进行部分修改。
请求是否有主体 也许有?
成功的响应是否有主体 否
安全 否
幂等 否
可缓存 否
HTML 表单是否支持 否
在HTTP协议中，?PUT?方法已经被用来表示对资源进行整体覆盖， 而?POST?方法则没有对标准的补丁格式的提供支持。不同于??PUT?方法，而与?POST?方法类似，PATCH??方法是非幂等的，这就意味着连续多个的相同请求会产生不同的效果。
请求主体
1.使用默认的?application/x-www-form-urlencoded?做为 content type 的简单表单:
2.使用?multipart/form-data?作为 content type 的表单:
?
示例
PATCH /api/example/1
?
?----------------------------------------------------------------------------------------------------------------
?
关于返回
- 当GET,PUT和PATCH请求成功时，要返回对应的数据，及状态码200，即SUCCESS
- 当PUT,POST创建数据成功时，要返回创建的数据，及状态码201，即CREATED
- 当DELETE删除数据成功时，不返回数据，状态码要返回204，即NO CONTENT
- 当GET不到数据时，状态码要返回404，即NOT FOUND
- 任何时候，如果请求有问题，如校验请求数据时发现错误，要返回状态码400，即BAD REQUEST
- 当API 请求需要用户认证时，如果request中的认证信息不正确，要返回状态码401，即NOT AUTHORIZED
- 当API 请求需要验证用户权限时，如果当前用户无相应权限，要返回状态码403，即FORBIDDEN
?
?
?
----------------------------------------------------------------------------------------------------------------
?
序列化和反序列化
?
序列化和反序列化是RESTful API开发中的一项硬需求，所以几乎每一种常用的开发语言都会有一个或多个优秀的开源库，来实现序列化和反序列化，因此，我们在开发RESTful API时，没必要制造重复的轮子，选一个好用的库即可,$.AJAX AXIOS FLY都可以！其他的语言的可以去git下（如 python中的marshmallow）。
?
----------------------------------------------------------------------------------------------------------------
?
?
数据校验
?
当客户端向服务器发出post,?put或patch请求时，通常会同时给服务器发送json格式的相关数据，服务器在做数据处理之前，先做数据校验，是最合理和安全的前后端交互。如果客户端发送的数据不正确或不合理，服务器端经过校验后直接向客户端返回400错误及相应的数据错误信息即可。常见的数据校验包括：
- 数据类型校验，如字段类型如果是int，那么给字段赋字符串的值则报错
- 数据格式校验，如邮箱或密码，其赋值必须满足相应的正则表达式，才是正确的输入数据
- 数据逻辑校验，如数据包含出生日期和年龄两个字段，如果这两个字段的数据不一致，则数据校验失败（目前而言最复杂）
?
?
----------------------------------------------------------------------------------------------------------------
?
Authentication 和 Permission
?
常用的认证机制是Basic Auth和OAuth，RESTful API 开发中，除非API非常简单，且没有潜在的安全性问题，否则，认证机制是必须实现的，并应用到API中去。Basic Auth非常简单，很多框架都集成了Basic Auth的实现，自己写一个也能很快搞定，OAuth目前已经成为企业级服务的标配，其相关的开源实现方案非常丰富。如：jsonwebtoken.js 等等
?
----------------------------------------------------------------------------------------------------------------
?
CORS
?
懒 难求的打字?自己跳过去看
?
node express CORS配置
app.all('*', (req, res, next) => {
res.header("Access-Control-Allow-Origin", "*");
res.header("Access-Control-Allow-Headers", "X-Requested-With,token,authorization");
res.header("Access-Control-Allow-Methods", "PUT,POST,GET,DELETE,PATCH,OPTIONS");
res.header("X-Powered-By", ' 3.2.1');
res.header("Content-Type", "application/json;charset=utf-8");
next();
});?
----------------------------------------------------------------------------------------------------------------
?
?
URL 规范
?
其命名和结构需要有意义。因此，在设计和编写URL时，要符合一些规范。
?
1. API 版本控制
?
规范的API应该包含版本信息，在RESTful API中，最简单的包含版本的方法是将版本信息放到url中，如：
GET /api/v1/posts/另一种优雅的做法是，使用HTTP header中的accept来传递版本信息。
GET /api/v2/posts/
?
2.URL应指向资源
?
URL应指向资源，而不是规定动作，动作由METHOD来决定
GET /api/Article/1/
3.GET 和HEAD必须安全
贼吉尔恐怖的一个案例
GET /api/deleteArticle?id=1?
4.使用?nested routing来获取一个资源子集
GET /api/lopo/Article/1/
如果语义上将资源子集看作一个独立的资源集合，则使用?nested routing?感觉更恰当，如果资源子集的获取是出于过滤的目的，则使用filter更恰当。
?
5.Filter
对于资源集合，可以通过URLSearchParams对资源进行过滤
GET /api/comp/?user=lopo&&column=id,name,labelPagination 案例
{
"page": 1, # 当前是第几页
"pages": 3, # 总共多少页
"per_page": 10, # 每页多少数据
"has_next": true, # 是否有下一页数据
"has_prev": false, # 是否有前一页数据
"total": 27 # 总共多少数据
}6.?Url 设计建议- Url 严格区分大小写的 不同大小写会被定为到不同的资源
- 建议以/对Url进行结尾
- 建议Url 片段组合时用-，params用_
?
?
?
?
