Restful API
文章目录
Restful API1、REST是什么以及它的 6 个限制REST是什么？REST的6个限制
2、 Restful是什么Restful是什么RESTful API具体什么样子？现实举例从资源出发
3、为什么要使用RestfulHTTP协议-URLHTTP协议-请求HTTP协议-响应RESTful架构与其他架构的区别效率和易用性安全性
4、 如何使用Restful资源路径HTTP动词过滤信息状态码错误处理返回结果
5、 小结6、参考资料
简单记录 - Restful API实战
Q：如何做到业务逻辑“一次编写，随时接入”？
A：通过远程调用API ，比较火的方案是“RESTful API”
RESTful是什么，简单来说，RESTful API 是基于HTTP协议产生的一种相对简单的API设计方案，属于无状态传输。下面介绍RESTful是什么-为什么-怎么使用
1、REST是什么以及它的 6 个限制
要想知道Restful是什么，先来了解下REST是什么吧。
REST是什么？
REST是什么？
万维网软件架构风格用来创建网络服务
起源：REST，是Roy Thomas Fielding在他2000年的博士论文中提出的。
REST，即Representational State Transfer的缩写, “表现层状态转化”。
表现层（Representation）：
我们把"资源"具体呈现出来的形式，叫做它的"表现层"（Representation）。
比如文本可以用txt格式表现，也可以使用JSON格式、二进制格式表现。
状态转化（State Transfer）：
数据和状态的变化
HTTP协议里面，POST、DELETE、PUT、GET增删改查，对应四种基本操作：
POST用来新建资源
DELETE用来删除资源
PUT用来更新资源
GET用来获取资源
数据在互联网进行传输
REST的6个限制
依然不明白REST？
那通过REST的6个限制详细了解它
客户-服务器（Client-Server）
关注点分离服务端专注数据存储，提升了简单性前端专注用户界面，提升了可移植性
数据存储 用户交互
无状态（Stateless）
所有用户会话信息都保存在客户端每次请求必须包括所有信息，不能依赖上下文信息服务端不用保存会话信息，提升了简单性、可靠性、可见性
缓存的作用
缓存（Cache）
所有服务端响应都要被标为可缓存或不可缓存减少前后端交互，提升了性能
统一接口（Uniform Interface）
接口设计尽可能统一通用，提升了简单性、可见性接口与实现解耦，使前后端可以独立开发迭代
分层系统（Layered System）
每层只知道相邻的一层，后面隐藏的就不知道了客户端不知道是和代理还是真实服务器通信其他层：安全性、负载均衡、缓存层等
按需代码（Code - On - Demand 可选）
客户端可以下载运行服务器传来的代码（比如 JS）通过减少一些功能，简化了客户端
统一接口的限制
资源的标识
资源是如何可以命名的事物，比如用户、评论等每个资源可以通过URI被唯一地标识
https://api.github.com/usershttps://api.github.com/users/liuawen
URI 统一资源标识符（Uniform Resource Identifier）
URL 统一资源定位器 （Uniform Resource Locator）
URI 唯一标识
网上的资源唯一地标识
提供表述来操作资源
表述就是Representation ，比如JSON、XML等客户端不能直接操作（比如SQL）服务端资源客户端应该通过表述（比如JSON）来操作资源
https://developer.github.com/v3/repos/
自描述信息
每个消息（请求或响应）必须提供足够的信息让接受者理解
媒体类型（application/json、application/xml）
HTTP方法：GET（查）、POST（增）、DELECT（删）
是否缓存：Cache-Control
HTTP verbs
HTTP协议 标准
超媒体作为应用状态引擎
超媒体：带文字的链接
应用状态：一个网页
引擎：驱动、跳转
合起来：点击链接跳转到另一个网页
2、 Restful是什么
Restful定义以及Restful对于资源的定义
Restful是什么
RESTful架构，就是目前流行的一种互联网软件架构
Restful
如果一个架构符合REST原则，就称它为RESTful架构。
符合REST架构风格的API
本质：一种软件架构风格
核心：面向资源
解决的问题：
降低开发的复杂性提高系统的可伸缩性
RESTful API具体什么样子？
基本的URI，如 https://api.github.com/users
标准HTTP方法，如GET,POST,PUT,PATCH,DELETE
传输的数据媒体类型，如JSON，XML
现实举例
GET / users # 获取users列表
GET /users/12# 查看某个具体的user
POST/users# 新建一个user
PUT /users/12# 更新user12
DELETE/users/12# 删除user12
从资源出发
从资源出发
设计概念和准则
网络上的所有事物都可以被抽象为资源。每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识。所有的操作都是无状态的。
资源
Q：那什么是资源呢？
A：所谓“资源”，就是网络上的一个实体，或者说是网络上的一个具体信息,可以是文本、图片、视频等
每种资源对应一个特定的URI（统一资源标识符（Uniform Resource Identifier））。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。
3、为什么要使用Restful
HTTP协议-URL
HTTP是一个属于应用层的协议，特点是简捷、快速。
schema：//host[:port]/path[?quert-string] [#anchor]
schema 指定底层使用的协议（例如：http，https,ftp）
host 服务器的IP地址或者域名
port 服务器端口，默认为80
path 访问资源的路径
query0string 发送给http服务器的数据
anchor 锚
HTTP协议-请求
HTTP协议-请求
组成格式：请求行、消息报头、请求正文
请求行
格式如下：Method Request-URI HTTP-Version CRLF
举例
GET / HTTP / 1.1 CRLF
请求方法
GET 请求获取Request-URI所标识的资源POST 在Request-URI所标识的资源后附加新的数据HEAD 请求获取由Request-URI所标识的资源的响应消息
获取
发送数据
PUT 请求服务器存储一个资源 ，并用Request-URI作为其标识DELETE 请求服务器删除Request-URI所标识的资源OPTIONS 请求查询服务器的性能，或者查询与资源相关的选项和需求
HTTP协议-响应
HTTP协议-响应
组成格式：状态行、消息报头、响应正文
状态行
HTTP-Version Status-Code Reason-Phrase CRLF
HTTP/1.1 200 OK
常用状态码
200 OK //客户端请求成功
400 Bad Request //客户端请求有语法错误，不能被服务器所理解
401 Unauthorized //服务器收到请求，但是拒绝提供服务
404 Not Found //请求资源不存在
5xx服务器错误
500 Internal Server Error //服务器发生不可预期的错误503 Server Unavailable //服务器当前不能处理客户端的请求
404 Not Found
RESTful架构与其他架构的区别
SOAP WebService
WebService是一种跨编程语言和跨操作系统平台的远程调用技术
WebService通过HTTP协议发送请求和接受结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。
WebService 、SOAP协议、RESTful架构与WebService
RESTful架构与其他架构的区别
效率和易用性
SOAP由于各种需求不断扩充本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。
RESTful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计,同时也最大限度的利用了Http最初的应用协议设计理念。
安全性
RESTful对于资源型服务接口来说很合适,同时特别适合对于效 率要求很高,但是对于安全要求不高的场景。
SOAP的成熟性可以给需要提供给多开发语言的, 对于安全性 要求较高的接口设计带来便利。所以觉得纯粹说什么设计模 式将会占据主导地位没有什么意义,关键还是看应用场景。
restful适合做什么开发 接口或者应用
4、 如何使用Restful
如何设计RESTful API
资源路径（URI）
HTTP动词
过滤信息
状态码
错误处理
返回结果
请求设计规范
URI使用名词，尽量用复数，如/usersURI使用嵌套表示关联关系，如 /users/12/repos/5使用正确的HTTP方法，如GET/POST/PUT/DELETE不符合CRUD的情况：POST/action/子资源
资源路径
在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词，一般来说API中的名词应该使用复数。goods、users等。
举例
举例来说,有一个API提供动物园( zoo )的信息,还包括各种动物和雇员的信息。则它的路径应该设计成下面这样。
https://api.example.com/v1/zoos //动物园资源
https://api.example.com/v1/animals //动物园资源
https://api.example.com/v1/employees //动物园资源
v1版本、http请求头中 或者 名词复数
获取一个动物 animals/id=1
资源的设计
http 动词 四种操作 创建 更新 读取 删除
HTTP动词
对于资源的操作（CURD），由HTTP动词（谓词）表示
GET：从服务器取出资源（一项或多项）。
POST：在服务器新建一个资源。
PUT：在服务器更新资源（客户端提供改变后的完整资源）
PATCH：在服务器更新资源（客户端提供改变的属性）。
DELETE：从服务器删除资源。
put更新资源 patch只会返回更新的数据 比如改密码 密码变了就返回密码。
举例
POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID: 更新某个指定动物园的信息
DELETE /zoos/ID:删除某个动物园
删除动物园，动物园里的动物都删除
POST新建 GET 获取 PUT 更新 DELETE 删除
过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。
API应该提供参数，过滤返回结果。
过滤信息，某个常数。
举例
?offset=10:指定返回记录的开始位置。?page=2&per_page=100:指定第几页，以及每页的记录数。?sortby=name&order=asc:指定返回结果排序，以及排序顺序。?animal_type_id=1:指定筛选条件。
过滤信息
用户自己设计的
offset开始位置
状态码
标准的
服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。
200 OK 服务器成功返回用户请求的数据，该操作是幂等的。201 CREATED created 新建或修改数据成功204 NO CONTENT 删除数据成功
200 OK
201新建修改204删除，用得比较少的。
400 BAD REQUEST request 用户发出的请求有错误，该操作是幂等的。401 Unauthorized 表示用户没有认证，无法进行当前操作。403 Forbidden 表示用户访问是被禁止的。
客户端的请求有问题
401 没有认证
403 提供了 但参数不足 或者权限不够
422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。500 INTERNAL SERVER ERROR internal server error 服务器发生错误，用户将无法判断发出的请求是否成功。
422
验证错误 后端需要用户名 密码 前端只提供了一个用户名 错误了 密码不能为空
500
服务器错误
错误处理
422 参数错误 500
错误处理
输出JSON格式错误信息
如果状态码是4xx或者5xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可
{
"error":"参数错误"
}
返回结果
输出JSON数组或JSON对象
返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范：
GET/collections:返回资源对象的列表（数组）
GET/collections/identity:返回单个资源对象
POST/collections:返回新生成的资源对象。
PUT/collections/identity：返回完整的资源对象
PATCH/collections/identity：返回被修改的属性
DELECT/collections/identity：返回一个空文档
不存在返回404
参数
PUT 完整的 PATCH更新的
DELETE 空的
设计RESTful API
表单不是只支持GET和POST提交么。那怎么支持put、delete请求方式呢不懂？
HTTP/1.1协议中共定义了八种方法（有时也叫“动作”）来表明Request-URI指定的资源的不同操作方式：具体方法可以上网查询
你说的表单指的是form表单吧，method 属性规定如何发送表单数据（表单数据发送到 action 属性所规定的页面）。表单数据可以作为 URL 变量（method=“get”）或者 HTTP post （method=“post”）的方式来发送。
5、 小结
RESTful设计要素
RESTful应用场景
基于HTTP请求头的身份认证
REST，即Representational State Transfer的缩写, “表现层状态转化”。
如果一个架构符合REST原则，就称它为RESTful架构。
解决的问题：
降低开发的复杂性提高系统的可伸缩性
基本的URI，如 https://api.github.com/users
标准HTTP方法，如GET,POST,PUT,PATCH,DELETE
传输的数据媒体类型，如JSON，XML
去选择 不能因为restful而restful 嗯嗯
6、参考资料
1、 理解RESTful架构
2、 Restful API实战
3、Node.js开发仿知乎服务端 深入理解RESTful API