RESTful API基础知识

1、Restful简介

（1）Restful是什么？

• 一种软件架构风格
• 面向资源
• 所有操作都是无状态的

（2）资源是什么？

所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。

每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识。

可以看下这个：如何给老婆解释什么是RESTful - 知乎 (zhihu.com)

2、Restful中的HTTP协议

（1）HTTP协议-URL

schema://host[:post]/path[?query-string][#anchor]

只要有协议头、主机名、请求路径即可，[]中的是可选参数。

scheme 指定低层使用的协议（例：http，https，ftp）

host 服务器的IP地址或者域名

port 服务器端口，http协议默认为80，https协议默认为443

path 访问资源的路径

query-string 发送给http服务器的数据

anchor 锚（？这个我还没用到过）

（2）HTTP协议-请求

组成格式：请求行、消息报头、请求正文

• 请求行

格式如下：Method Request-URI HTTP-Version CRLF

对应为：请求方法 请求地址(统一资源标识符) HTTP协议版本号 回车和换行

例：GET /test.html HTTP/1.1 (CRLF)

• 请求方法

GET 请求获取Request-URI(统一资源标识符)所标识的资源

POST 在Request-URI所标识的资源附加新的数据

HEAD 请求获取由Request-URI所标识的资源的响应消息报头

PUT 请求服务器存储一个资源，并用Request-URI作为其标识

DELETE 请求服务器删除Request-URI所标识的资源

OPTIONS 请求查询服务器的性能，或者查询与资源相关的选项和需求

（3）HTTP协议-响应

组成格式：状态行、消息报头、响应正文

• 状态行

格式如下：HTTP-Version Status-Code Reason-Phrase CRLF

对应为：HTTP协议版本号 响应状态码 状态码的文本描述 回车和换行

例：HTTP/1.1 200 OK (CRLF)

状态码由三位数字组成，第一个数字定义了响应的类别。有5种可能的取值：

1XX 指示信息（表示请求已接收，继续处理）

2XX 成功（表示请求已被成功接收、理解、接受）

3XX 重定向（要完成请求必须进行更进一步的操作）

4XX 客户端错误（请求有语法错误或请求无法实现）

5XX 服务器端错误（服务器未能实现合法的请求）

 

 

• 常用状态码

200 OK  客户端请求成功

400 Bad Request  客户端请求有语法错误，不能被服务器所理解

401 Unauthorized  服务器收到请求，但是拒绝提供服务

404 NOT Found  请求资源不存在

500 Internal Server Error  服务器发生不可预期的错误

503 Server Unavailable  服务器当前不能处理客户端的请求

更多内容可参考：HTTP基础：URL格式、 HTTP请求、响应、消息_技术大牛聂小小诚的博客-CSDN博客

3、Restful API应用场景

Restful对于资源型服务接口来说很合适，同时特别适合对于效率要求很高，但是对于安全要求不高的场景。

(刚接触，还没心得体会。后续补充)

4、如何设计Restful API？

资源路径（URI）、HTTP动词、过滤信息、状态码、错误处理、返回结果

（1）资源路径

在Restful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数。

例：

一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计为：

https://api.com/v1/zoos;  //动物园资源

https://api.com/v1/animals; //动物资源

https://api.com/v1/employees; //雇员资源

（2）HTTP动词

对于资源的操作（CURD），由HTTP动词表示。

GET：从服务器取出资源（一项或多项）。

POST：在服务器新建一个资源。

PUT：在服务器更新资源（客户端提供改变后的完整资源）。

PATCH：在服务器更新资源（客户端提供改变的属性）。

DELETE：从服务器删除资源。

例：

POST /zoos 新建一个动物园

GET /zoos/ID 获取某个指定动物园的信息

PUT /zoos/ID 更新某个指定动物园的信息

DELETE /zoos/TD 删除某个动物园

（3）过滤信息

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

例：

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

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

?sortby=name&order=asc  指定返回结果排序，以及排序顺序

?animal_type_id=1 指定筛选条件

（4）状态码

服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。

200 OK 服务器成功返回用户请求的数据，该操作是幂等的。

201 CREATED 新建或修改数据成功。

204 NO CONTENT 删除数据成功。

400 BAD REQUEST 用户发出的请求有错误，该操作是幂等的

401 Unathorized 表示用户没有认证，无法进行当前操作。

403 Forbidden 表示用户访问是被禁止的。

422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。

500 INTERNAL SERVER ERROR 服务器发生错误，用户将无法判断发出的请求是否成功。

（5）错误处理

如果状态码是4XX或者5XX，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

（6）返回结果

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

GET /collections 返回资源对象的列表（数组）

GET /collections/identity 返回单个资源对象

POST /collections 返回新生成的资源对象

PUT /collections/identity 返回完整的资源对象

PATCH /collections/identity 返回被修改的属性

DELETE /collections/identity 返回一个空文档