Restful API是什么、为什么、怎么使用

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架构

2、 Restful API实战

3、Node.js开发仿知乎服务端 深入理解RESTful API