Restful API
文章目录
简单记录 - 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/users
- https://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使用名词，尽量用复数，如/users
- URI使用嵌套表示关联关系，如 /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架构