文章/答案/技术大牛

发布

社区首页 >专栏 >【RESTful】RESTful API 接口设计规范 | 示例

【RESTful】RESTful API 接口设计规范 | 示例

前端修罗场

发布于 2023-10-07 10:27:28

1.8K01

代码可运行

文章被收录于专栏：Web 技术Web 技术

运行总次数：1

代码可运行

概念

本质：一种软件架构风格核心：面向资源设计的API

解决问题：

降低开发的复杂性
提高系统的可伸缩性

例如：设计一套API，为多个终端服务。

设计概念和准则

网络上的所有事物都可以被抽象为资源
每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识
所有的操作都是无状态的（本次操作、下次操作、上次操作之间无关系）

资源：网络上的一个实体、具体信息。

HTTP

RESTful 与HTTP协议操作无关，但是它是按照HTTP的思想进行设计的，所以有必要知道HTTP

参考官方文档：https://tools.ietf.org/html/rfc2616

schema://host[:port]/path[?query-string][#author]

shceme 指定低层使用的协议（如http,https,ftp）
host 服务器的IP地址或域名
port 服务器端口，默认为80
path 访问资源的路径
query-string 发送给http服务器的数据，常用于对资源进行筛选操作
anchor 锚，链接

请求

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

请求行格式： 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-Version Status-Code Reason-Phrase CRLF

如： HTTP/1.1 200 OK

常用响应状态码（在RESTful 中有重要应用）

200 OK //客户端请求成功

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

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

404 Not Found //请求资源不存在

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

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

RESTful 架构与其他架构的区别

API 的开发方式不止一种，另一种比较流行的开发方式是SOAP WebService。

SOAP WebService

WebService 是一种跨编程语言和跨操作系统平台的远程调用技术。其通过HTTP协议发送请求和接收结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。

对比

效率与易用性：SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。而RESTful API 在请求方法、资源、地址都进行了规范，其最大限度的利用了HTTP最初的应用协议的设计理念。
安全性：RESTful 对于资源型服务器接口比较适合，适合对于效率要求很高，但是对于安全要求不高的场景。SOAP 的成熟性可以给需要提供给多开发语言的，对于安全性的要求较高的接口设计带来便利，你可以在客户端和服务端应用证书进行安全措施。所以关键看应用场景。

使用RESTful

设计RESTful API

资源路径（URI）：RESTful的核心是面向资源，如何规划资源路径很重要
HTTP动词(请求方式)：如get,post,delete,put
过滤信息：例如获取资源列表时有分页操作/查询操作，这时要合理分配过滤信息，过滤信息设置太多，有可能会违反RESTful API 关于URI方面的限定。
状态码：当客户端发送一个请求时，服务端应当响应什么状态码
错误处理：如当发现客户端传入的参数有问题时，该返回什么样的状态信息。
返回结果：如POST资源的时候，需要返回一个资源实例；GET资源列表时，需要返回一个资源数组；

资源路径

在RESTful架构中，每个网址代表一个资源，所以网址中不能有动词，只能有名词。一般而言，API中的名词应该使用复数。例如，使用users反映用户资源的URI，而不是使用user。

例如：有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，那么它的资源路径应设计成如下样子。

https://api.example.com/v1/zoos  //动物园资源。使用https协议头;加入v1版本号，因为以后可能会更改api。版本号的加入有两种做法，一种是加入到地址中，另一种是加入到HTTP请求头中;zoos复数

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

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

HTTP动词

对资源的操作有创建、读取、更新、删除(CURD)，由HTTP动词表示。

GET ：从服务器去除资源
POST ：在服务器新建一个资源
PUT：在服务器更新资源（客户端提供改变后的完整资源，服务端返回完整的更新字段）
PATCH：在服务器更新资源（客户端提供改变的属性，服务端返回只发生了更新的字段）
DELETE：从服务器删除资源

例如：

POST/zoos : 新建一个动物园
GET/zoos/ID : 获取某个指定动物园的信息
PUT/zoos/ID : 更新某个指定动物园的信息
DELETE/zoos/ID : 删除某个动物园

过滤信息

如果记录数量过多，服务器不可能都将它们返回给用户。这时就需要进行筛选。筛选时，API应该提供一个参数，过滤一下返回的结果。

例如：

?offset = 10 :指定返回记录的开始位置
?page = 2&per_page = 100 :指定第几页，以及每页的记录数
?sortby = name&order = asc :指定返回结果排序，以及排序顺序
?animal_type_id = 1 :指定筛选条件

状态码

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

200 OK 服务器成功返回用户请求的数据
201 CREATED 新建或修改数据成功
204 NO CONTENT 删除数据成功
400 BAD REQUEST 用户发出的请求有错误
401 Unauthorized 表示用户没有认证，无法进行当前操作
403 Forbidden 表示用户的访问是被禁止的
422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。例如创建用户资源时需要用户名、密码，而前端只提供用户名字段，那么就要返回一个422 状态码，并返回错误信息：”密码不能为空“
500 INTERNAL SERVER ERROR 服务器内部错误，此时服务端无法处理任何请求。