rest api 设计规范

kongguoan

已于 2023-01-09 22:04:08 修改

阅读量277

点赞数

分类专栏：技术1+1 文章标签：设计规范 Powered by 金山文档

于 2023-01-09 22:03:27 首次发布

技术1+1 专栏收录该内容

2 篇文章 0 订阅

订阅专栏

什么是REST API

一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

请求方法解释

方法	描述	返回	是否幂等
PATCH	Create/Modify the resource with JSON Merge Patch	200-OK, 201-Created	False
PUT	Create/Replace the whole resource	200-OK, 201-Created	True
POST	Create new resource (ID set by service)	201-Created with URL of created resource	False
POST	Action	200-OK, 204-No Content (only when nothing returned in response body)	False
GET	Read (i.e. list) a resource collection	200-OK	True
GET	Read the resource	200-OK	True
DELETE	Remove the resource	204-No Content; avoid 404-Not Found	True

常见的 API 模式

网址结构

单个资源

https://.../<resource-collection>/<resource-id>

多个资源

https://.../<resource-collection>

示例

GET /zoos：列出所有动物园

POST /zoos：新建一个动物园

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

PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）

PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）

DELETE /zoos/ID：删除某个动物园

GET /zoos/ID/animals：列出某个指定动物园的所有动物

DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

执行操作

REST 规范用于对资源的状态进行建模，主要用于处理 CRUD（创建、读取、更新、删除）操作。但是，许多服务需要对资源执行操作的能力，例如获取图像的缩略图或重新启动 VM。有时对集合执行操作也很有用。

规则一

在 Azure 中，我们建议通过将“：”后跟操作谓词追加到最终路径段来区分操作操作

对一个资源进行操作时候应该按照如下方式

POST https://.../<resource-collection>/<resource-id>:<action>?<input parameters>

example:

https://.../users/Bob:grant?access=read

对一个资源集合进行操作时候

POST https://.../<resource-collection>:<action>?<input parameters>

example

https://.../users:grant?access=read

注意：为了避免操作和id重复，应该避免在id中使用“：”号

对资源或集合的任何操作应该使用使用 POST

支持Repeatability-Request-ID和Repeatability-First-Sent请求头，如果重试发生时动作需要幂等

action应该是动词

禁止在当操作行为可以合理地定义为标准 REST 创建、读取、更新、删除或列表操作之一时使用该方式

参数多的时候可以放到body

规则二

POST https://.../<resource-collection>/<resource-id>/<action>?<input parameters>

example

https://.../services/1/restart

API Versioning

在发布新的预览版时，服务团队可能会在给客户至少 90 天的时间来升级他们的代码后，完全淘汰任何以前的预览版

不要在任何操作路径中包含版本号段。

从预览 API 过渡到 GA API 时，请勿使用相同的日期。如果预览版 api-version 为 '2021-06-04-preview'，则 API 的 GA 版本必须晚于 2021-06-04 的日期

不要将预览功能保留超过 1 年；它必须在引入后 1 年内 GA（或被删除）。

示例

PUT https://service.azure.com/users/Jeff?api-version=2021-06-04

PUT https://service.azure.com/users/Jeff?api-version=2021-06-04-preview

发现 API 版本的示例请求

OPTIONS /?comp=list HTTP/1.1

host: accountname.blob.core.azure.net

示例响应

200 OK

api-supported-versions: 2011-08,2012-02,1.1,2.0

api-deprecated-versions: 2009-04,1.0

Content-Length: 0

长时间运行的操作

基于资源的长时间运行的操作（RELO）

客户端向资源发送初始请求以启动长时间运行的操作。此初始请求可以是 PUT、PATCH、POST 或 DELETE 方法。

资源验证请求并启动操作处理。它使用 200-OK HTTP 状态代码（如果操作是创建操作，则为 201-Created）和资源表示形式向客户端发送响应，其中状态字段设置为指示操作处理已开始的值.

客户端然后向资源发出 GET 请求以确定操作处理是否已完成。资源以资源的表示进行响应。当操作仍在处理中时，状态字段将包含一个“非终端”值，如处理中。

操作处理完成后，来自客户端的 GET 请求将收到响应，其中状态字段包含“终端”值——Succeeded、Failed 或 Canceled——指示操作的结果。

带有状态监视器的长时间运行的操作（LRO）

在具有状态监视器的 LRO 模式中，操作的状态和结果被封装到状态监视器资源中，该资源不同于目标资源并且特定于单个操作请求。下面是状态监视器 LRO 模式的样子

客户端发送请求以启动长时间运行的操作。与 RELO 模式一样，初始请求可以是 PUT、PATCH、POST 或 DELETE 方法。

资源验证请求并启动操作处理。它使用 202-Accepted HTTP 状态代码向客户端发送响应。此响应中包含一个 Operation-location 响应标头，其中包含此特定操作的状态监视器的绝对 URL。该响应还包括一个 Retry-after 标头，告诉客户端在向状态监视器 URL 发送请求之前等待的最短时间（以秒为单位）。

状态监视器 URL 响应有关操作的信息，包括其当前状态，应表示为名为 status 的字段中一组固定的字符串值之一。如果操作仍在处理中，状态字段将包含一个“非终端”值，如Processing。

操作处理完成后，对状态监视器 URL 的 GET 请求会返回一个响应，其中的状态字段包含一个终端值——Succeeded、Failed 或 Canceled——指示操作的结果。如果状态为Failed，则状态监视器资源必须包含一个错误字段，其中包含描述失败的代码和消息。如果状态为成功，则响应可能包含适当的附加字段，例如processing。