RESTful API
RESTful API
一、RESTful简介
1.Restful是什么
本质：一种软件架构风格
核心：面向资源
解决的问题：
①降低开发的复杂性
②提高系统的可伸缩性
2.设计概念和准则
①网络上所有事物都可以被抽象为资源。
②每一个资源都有唯一的资源标示，对资源的操作不会改变这些标示
③所有的操作都是无状态的
资源:一张图片、一个文本、一首歌曲、一个视频等
所谓“资源”，就是网络上的一个实体，或者说是网络上的一个具体信息。
二、HTTP协议
1.URL
HTTP是一个属于应用层的协议，特点是简洁、快速。
schema://host[:port]/path[?query-string][#anchor]
shceme:指定低层使用的协议（例如：http,https,ftp）
host:服务器的IP地址或者域名
port:服务器端口，默认为80
path：访问资源的路径
query-string：发送给http服务器的数据
anchor：锚
2.请求
①组成格式：请求行、消息报头、请求正文
②请求行：
格式如下：Method Request-URI HTTP-Version CRLF
举例：GET/HTTP/1.1CRLF
③请求方法
- GET 请求获取Request-URI所标识的资源
- POST 在Request-URI所标识的资源后附加新的数据
- HEAD 请求获取由Request-URI所标识的资源的响应消息报头
- PUT 请求服务器存储一个资源，并用Request-URI作为其标识（更新资源）
- DELETE 请求服务器删除Request-URI所标识的资源
- OPTIONS 请求查询服务器的性能，或者查询与资源相关的选项和需求
3.响应
①组成格式：状态行、消息报头、响应正文
②状态行：
HTTP-Version Status-Code Reason-Phrase CRLF
HTTP/1.1 200 OK
③常用状态码
- 200 OK //客户端请求成功
- 400 Bad Request //客户端请求有语法错误，不能被服务器所理解
- 401 Unauthorized //服务器收到请求，但是拒绝提供服务
- 404 Not Found //请求资源不存在
- 500 Internal Server Error //服务器发生不可预期的错误
- 503 Server Unavailable //服务器当前不能处理客户端的请求
三、RESTful架构与其他架构的区别
1.SOAP WebService
WebService是一种跨编程语言和跨操作系统平台的远程调用技术。
WebService通过HTTP协议发送请求和接收结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。
2.效率和易用性
SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性以及学习成本上也有所增加。
RESTful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了Http最初的应用协议设计理念。
3.安全性
RESTful对于资源型服务接口来说很合适，同时特别适合对于效率要求很高，但是对于安全要求不高的场景。
SOAP的成熟性可以给需要提供多开发语言的，对于安全性要求较高的接口设计带来便利。所以我觉得纯粹说什么设计模式将会占据主导地位没有什么意义，关键还是看应用场景。
四、如何设计RESTful API
1.资源路径（URI）
在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数。
举例：有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样：
https://api.example.com/v1/zoos //动物园资源（v1：版本号）
https://api.example.com/v1/animals//动物资源
https://api.example.com/v1/employees//雇员资源
版本号：两种做法：
1.直接加在url中。
2.加入到http请求头中
https://api.example.com/v1/animals//动物资源：
获取一个动物：https://api.example.com/v1/animals/id=1
删除一个动物：delete：https://api.example.com/v1/animals/id=1
2.HTTP动词
对于资源的操作（CURD），由HTTP动词（谓词）表示。
- GET：从服务器取出资源（一项或多项）。
- POST：在服务器新建一个资源。
- PUT：在服务器更新资源（客户端提供改变后的完整资源）
- PATCH：在服务器更新资源（客户端提供改变的属性）
- DELETE：从服务器删除资源。
举例：
POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID:更新某个指定动物园的信息
DELETE /zoos/ID:删除某个动物园
3.过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。
API应该提供参数，过滤返回结果。
举例：
?offset=10:指定返回记录的开始位置
?page=2&per_page=100:指定第几页，以及每页的记录数
?sortby=name&order=asc:指定返回结果排序，以及排序顺序。
?animal_type_id=1:指定筛选条件
4.状态码
服务器向用户返回的状态码和提示信息，使用标准HTTP状态码
- 200 OK 服务器成功返回用户请求的数据，该操作是幂等的
- 201 CREATED 新建或修改数据成功
- 204 NO CONTENT 删除数据成功
- 400 BAD REQUEST 用户发出的请求有错误，该操作是幂等的。
- 401 Unauthorized 表示用户没有认证，无法进行当前操作。
- 403 Forbidden 表示用户访问是被禁止的。
- 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。
- 500 INTERNAL SERVER ERROR 服务器发生错误，用户将无法判断发出的请求是否成功
注意：
401是用户没有提供任何认证的选项或参数，服务端直接拒绝
403提供了认证参数，但参数错误或权限不足等。
422：创建用户资源，需要用户名和密码，而前端只提供了用户名，此时返回422，在响应体中加入错误信息：密码不能为空
5.错误处理
如果状态码是4xx或者5xx，就应该向用户返回出错信息。
一般来说，返回的信息中将error作为键名，出错信息作为键值即可
{
"error":"参数错误"
}
6.返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范：
- GET /collections:返回资源对象的列表（数组）
- GET /collections/identity:返回单个资源对象（如果改资源不存在，返回404）
- POST /collections:返回新生成的资源对象
- PUT /collections/identity:返回完整的资源对象
- PATCH /collections/identity:返回被修改的属性
- DELETE /collections/identity:返回一个空文档
附：HTTP状态码：
- 301—永久移动。被请求的资源已被永久移动位置；
- 302—请求的资源现在临时从不同的 URI 响应请求；
- 305—使用代理。被请求的资源必须通过指定的代理才能被访问；
- 307—临时跳转。被请求的资源在临时从不同的URL响应请求；
- 400—错误请求；
- 402—需要付款。该状态码是为了将来可能的需求而预留的，用于一些数字货币或者是微支付；
- 403—禁止访问。服务器已经理解请求，但是拒绝执行它；
- 404—找不到对象。请求失败，资源不存在；
- 406—不可接受的。请求的资源的内容特性无法满足请求头中的条件，因而无法生成响应实体；
- 408—请求超时；
- 409—冲突。由于和被请求的资源的当前状态之间存在冲突，请求无法完成；
- 410—遗失的。被请求的资源在服务器上已经不再可用，而且没有任何已知的转发地址；
- 413—响应实体太大。服务器拒绝处理当前请求，请求超过服务器所能处理和允许的最大值。
- 417—期望失败。在请求头 Expect 中指定的预期内容无法被服务器满足；
- 418—我是一个茶壶。超文本咖啡罐控制协议，但是并没有被实际的HTTP服务器实现；
- 420—方法失效。
- 422—不可处理的实体。请求格式正确，但是由于含有语义错误，无法响应；
- 500—服务器内部错误。服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理；
