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

Restful API

文章目录

  • Restful API
  • 1、REST是什么以及它的 6 个限制
    • REST是什么?
    • REST的6个限制
  • 2、 Restful是什么
    • Restful是什么
    • RESTful API具体什么样子?
    • 现实举例
    • 从资源出发
  • 3、为什么要使用Restful
    • HTTP协议-URL
    • HTTP协议-请求
    • 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/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

你可能感兴趣的:(实战,REST,Restful,API,http)