RESTFUL API 概述

什么是API

​ Api 简称接口。

​ 就是预先定义的函数，目的是能够让应用程序或开发人员能够具有访问指定网络资源的能力，而又无需关心访问的源码，或理解内部工作机制的细节。

API 的产生

  • Web
  • Android
  • IOS

由一个地方统一提供API 接口，多个平台直接调用这个API 接口获取信息。

实例

获取用户列表的接口设计

web 端：		https://api.qq.com/user/geyUserList?from=web
Andriod端：	https://api.qq.com/user/geyUserList?from=andriod
IOS端：		https://api.qq.com/user/geyUserList?from=ios
H5端：		https://api.qq.com/user/geyUserList?from=h5

Restful 风格的产生

不同开发者对获取用户列表的接口设计

https://api.qq.com/user/getUserList?from=***

https://qpi.qq.com?m=user&c=getUserList?from=***

https://qq.com/api/user/getUserList?from=***

https://qq.com?m=api&c=user&a=getUserList?from=***

Restful Api 的结构设计就诞生了。

Rest 是 ”Representational state transfer“ 的缩写， 可以翻译成“表现型状态转换”

基本概念

  • Restful 中一切都被认为是资源，每个资源都有对应的URI 标识（Uniform Resource Identifier，统一资源定位符https://blog.csdn.net/qq_32595453/article/details/80563142）。

  • 处理资源使用POST、GET、PUT、DELETE 等http 方法实现 创建、读取、修改、删除的操作。

  • 客户端通过四个 HTTP 动词，对服务器端资源进行操作，实现 “表现层状态转化”。

  • 表现是指资源的表现，客户端和服务端之间，传递这种资源的某种表现层；

  • 每个请求都是独立的，从客户端到服务器的每个请求都必须包含所有的必要信息。

注意：

  • 它只是一种设计风格而不是标准，只是提供了一组设计原则和约束条件；

  • 它主要应用于客户端和服务器端交互的软件；

  • 更简洁，更有层次、更易于实现缓存机制。

Restful API 规范

1、协议

Restful Api 于用户的通信协议，总是使用http 协议

2、域名

应该尽量将Api 部署再专用域名之下。

https://api.example.com

如果确定Api 很简单，不会有进一步扩展，可以考虑放在主域名下。

https://example.com/api/

3、版本

应该将Api 的版本号放入URL

https://api.example.com/version/

另一种做法是，将版本号放在http 头信息中，但不如放在URL 直观和方便。

4、路径

路径又称”终点“（endpoint）,表示Api 的具体网址。

在Restful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词而且所用的名词往往与数据库的表名对应。一般来说，数据库中的表都是同种记录的”集合“，所以Api 中的名词也往往应该使用复数。

举例来说，有一个Api 提供动物园（Zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos

https://api.example.com/v1/animals

https://api.example.com/v1/employees

5、http 动词

对于资源的具体操作类型，由http 动词表示。

常用的http 动词由下面四个：

POST(CTREATE):在服务器新建一个资源

DELETE(DELETE):从服务器删除资源

PUT(UPDATE):在服务器更新资源（客户端提供改变后的完整资源）

GET(SELECT):从服务器取出资源（一项或多项）

补充：PATCH方法是新引入的，是对PUT方法的补充，用来对已知资源进行局部更新

6、过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户，Api 应该提供参数，过滤返回结果。

?limit=10: 指定返回记录的数量

?offset=10: 指定返回记录的开始位置

?page=2&per_page=100: 指定第几页，以及每页的记录数

?sortby=name&order=asc: 指定返回结果按照哪个属性排序，以及排序顺序

?animal_type_id=1: 指定筛选的条件

7、状态码

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号是该状态码对应的http 动词

）。

200 OK -[GET]:服务器成功返回用户请求的数据

201 CREATED -[POST/PUT/PATCH]:用户新建或修改数据

202 Accepted -[*]:表示一个请求已经进入后台排队（异步任务）

204 NO CONTENT -[DELETE]:用户删除数据成功

400 INVALID REQUEST -[POST/PUT/PATCH]: 用户发出的请求有错误，服务器没有进行新建或修改数据的操作

401 Unauthorized -[*]:表示用户没有权限（令牌、用户名、密码错误）

403 Forbidden -[*]: 用户得到授权（与401相对），但是访问时被禁止的

404 Not Found -[*]: 用户发出的请求针对的时不存在的记录，服务器没有进行操作，该操作时幂等的

406 Not Acceptable -[GET]:用户请求的格式不可得（比如用户请求的时JSON格式，但是只有XML格式）

410 Gone -[GET]: 用户请求的资源被永久删除，且不会再得到的

422 Unprocesable entity -[POST/PUT/PATCH]:当创建一个对象时，发生一个验证错误。

500 Internal Server Error -[*]:服务器发生错误，用户将无法判断发出的请求是否成功

8、错误处理

如果产生错误，就应该像用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
	error: "Invalid API key"
}

9、返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection: 返回资源对象的列表
GET /collection/resource: 返回单个资源对象
POST /collection: 返回新生成的资源对象
PUT /collection/resource: 返回完整的资源对象
PATHCH /collection/resource: 返回完整的资源对象
DELETE /collection/resource: 返回一个空文档

Resyful、Soap以及RPC 对比

概念

REST：

​ 一种架构设计风格，提供了设计原则和约束条件。

RPC：（远程过程调用）

​ 是一种允许分布式应用程序调用网络上不同计算机的可用服务（函数/方法）的机制。

远程过程调用发展历程：

  • ONC RPC（开放网络计算机的远程过程调用），OSF RPC（开放软件基金会的远程过程调用）

  • CORBA（Common Object Request Broker Architecture 公共对象请求代理体系结构）

  • DCOM （分布式组件对象模型），COM+

  • Java　RMI

  • .NET Remoting

  • XML-RPC，SOAP，Web Service

  • PHPRPC，Hession，JSON-RPC

  • Microsoft WCF，WebAPI

  • ZeroC Ice，Thrift，GRPC

  • Hprose

SOAP：（简单对象访问协议）XML-RPC（Simple Object Access Protocol）

​ SOAP 是交换数据的一种协议规范，是一种轻量级的、简单的、基于XML 的协议规范。

​ SOAP 最主要的工作是使用标准的XML 描述了RPC 的请求信息（URI/类/方法/参数/返回值），理论上SOAP 就是一段XML，你可以通过http,smtp 等发送它。并且SOAP 也是跨语言的。

说明：SOAP 是基于 RPC 的

区别

REST 与 SOAP

概念方面：

​ rest 和 soap 接口时完全不同的两种数据通信接口，前者使用的时http 协议通信，请求的响应可以是 xml 也可以是 json。后者使用的是soap 协议通信，通信请求和响应都是xml ，而且有wsdl 作为请求和响应信息的标准。

核心不同：

​ rest 是基于http 之上建立的一种接口规范，核心是资源。soap 本身是一种子协议，以xml 格式传输。soap 的web 服务以操作为中心的。

协议方面：

​ Restful 使用标准的http 方法（POST/DELETE/PUT/GET）来抽象所有web 系统的服务能力，soap 应用都通过自己个性化的接口方法来抽象web 服务

安全控制方面：

​ 代理服务器可以指定安全策略，一般代理服务器的实现根据（URI，HTTP Method）两元组来决定http 请求的合法性。当发现Delete 这样的请求时，予以拒绝。对于soap ，如果我们向借助于既有的代理服务进行安全控制，会比较尴尬。因为代理服务器需要解释soap 的协议，这显然是不合理的。

缓存方面：

​ http GET 请求被设计用来节省客户端于服务器端之间的网络传输带来的开销，这也给客户端实现Cache 机制提供了可能。Rest 的应用可以充分挖掘http 协议对缓存支持的能力。而所有经过缓存服务器的soap 消息总是 http POST ，缓存服务器如果不解码soap 消息体，没法知道该http 请求是否想从服务器获得数据。决定了基于soap 应用的缓存机制要远比Rest 复杂。

总结：

​ 基于soap 构建的系统，其系统的扩展能力要强于soap ，这可以体现在它的统一接口抽象、代理服务器支持、缓存服务器支持等诸多方面。并且，伴随着Web Site as Web Services 演进的趋势，有理由相信rest 将会成为Web 服务领域的一个重要架构实践领域。

HTTP 协议

http 的重要性：

1、web service http+xml

2、Rest 大型架构 http+json/xml

3、各种Api

4、采集、小偷程序

5、Ajax

Rest 是Http 驱动的，并且完全发挥了Http 的能力。

Http 是什么：

​ 一种web 常见的应用层网路协议，全程为超文本传输协议。

​ 作为协议，http 仅仅是将通信过程规范化，是客户端于服务器端能够更好的理解对方想要表达的内容。

​ http 是基于TCP 传输层实现的，默认的TCP 端口为80

Http的版本发展

1、Http 0.9 版本 1991年

​ HTTP 0.9是第一个版本的HTTP协议，已过时。它的组成极其简单，只允许客户端发送GET这一种请求，且不支持请求头。由于没有协议头，造成了HTTP 0.9协议只支持一种内容，即纯文本。不过网页仍然支持用HTML语言格式化，同时无法插入图片。

2、Http 1.0 版本 1996年

​ HTTP协议的第二个版本，第一个在通讯中指定版本号的HTTP协议版本，至今仍被广泛采用。相对于HTTP 0.9 增加了如下主要特性：

  • 请求与响应支持头域
  • 响应对象以一个响应状态行开始
  • 响应对象不只限于超文本
  • 开始支持客户端通过POST方法向Web服务器提交数据，支持GET、HEAD、POST方法
  • 支持长连接（但默认还是使用短连接），缓存机制，以及身份认证

3、Http 1.1 版本 1997年

​ HTTP协议的第三个版本是HTTP 1.1，是目前使用最广泛的协议版本

4、http 2 版本 2015年

​ HTTP 2.0是下一代HTTP协议，目前应用还非常少。

5、Https

​ Https 是 Http 协议的安全版本，Http 协议的数据传输时明文的，是不安全的，Https 使用了SSL/TLS 协议进行了加密处理。

http 的特点

1、http 协议是无状态的

​ 就是说每次Http 请求都是独立的，任何两个请求之间没有什么必然的联系。

2、多次Http 请求

​ 在客户端请求网页时多数情况下并不是一次请求就能成功的，服务端首先是响应html 页面，然后浏览器收到响应后发现html 页面还引用了其他的资源，例如，CSS，JS 文件，图等，还会自动发送Http 请求这些需要的资源。现在的http 版本支持管道机制，可以同时请求和响应多个请求，大大提高了效率。

3、基于TCP 协议

​ Http 协议的目的是规定客户端和服务端数据传输的格式和数据交互的行为，并不负责数据传输的细节。底层是基于TCP 实现的。现在使用的版本当中默认是持久连接的，也就是多次http 请求使用一个TCP 连接。

Http 的组成

​ Http 协议分为请求和响应两部分，请求是指客户端向服务端发送的消息，响应是指服务器收到消息后向客户端返回的消息。

URI（统一资源标识符）

http://user:pass@host.com:8080/p/a/t/h?query=string#hash

http协议名称
user用户名(可选)
pass对应密码（可选）
host.com主机域名地址（也可以是IP地址）
8080端口号，默认是80
/p/a/t/h资源路径
query=string参数传递
hash锚点（即当前页面的相对位置）

Http 请求与响应

请求：（3个组成部分）

1、请求行
2、请求头信息
3、请求主体信息

请求头信息与请求行信息之间要有一个空行

请求格式：

请求行 （方法、路径、协议）
请求头信息 （合适为key:value）
空行
请求体信息 （可选）（发送的内容）

例子：
POST index.php  http/1.1
host:locahlhost
content-type:application/x-www-form-urllencoded
content-length:25

name=zhangsan

请求行

1、请求方法

​ GET POST HEAD DELETE PUT TRACE OPTIONS

​ 浏览器能发送Http 请求，那么Http 请求一定要浏览器发送吗？

2、请求路径

​ 请求路径是url 的一部分

3、所用协议

​ http协议 常用的版本是http 1.1 0.9和1.0 几乎没有人使用了

请求头信息

1、post 请求头要注明请求主体的长度

​ content-length:length

2、服务器要想能解析到post 数据，还需要请求头包含数据类型

​ content-type:application/x-www-form-urllencoded

请求体

​ 使用&拼接在一起的key=value 键值对

​

响应格式

响应行(协议  状态码  状态文字)
响应头信息（格式为key-value）
空行
主体信息（也可能没有）

例子：
Http/1.1  200 OK
content-type:text/html
content-length:25

hello

Http 状态码与状态文字

状态码用来反映服务器响应状态

状态文字是用来描述状态码的

Http 状态码分类

1**信息，服务器收到请求，需要请求者继续执行操作
2**成功，操作被成功接收并处理
3**重定向，需要进一步的操作以完成请求
4**客户端错误，请求包含语法错误或无法完成请求
5**服务器错误，服务器在处理请求的过程中发生了错误
# java # java-ee
Logo
CSDN学习社区

CSDN联合极客时间，共同打造面向开发者的精品内容学习社区，助力成长！

更多推荐

cover

用 OpenAI Assistants 做大模型应用开发

avatar CSDN学习社区
cover

1 小时解读鸿蒙 10 大热点问题

avatar CSDN学习社区
cover

1 小时解读鸿蒙 10 大热点问题

avatar CSDN学习社区