知识分享之规范——RESTful API规范

背景

知识分享之规范类别是我进行整理的日常开发使用的各类规范说明，作为一个程序员需要天天和各种各样的规范打交道，而有些规范可能我们并不是特别了解，为此我将一些常见的规范均整理到知识分享之规范系列中，便于小伙伴们快速翻阅学习。

参考文献


​​https://restfulapi.net/​​​​https://www.redhat.com/zh/topics/api/what-is-a-rest-api​​


起源

REST 是 REpresentational State Transfer的首字母缩写，是分布式超媒体系统(distributed hypermedia systems)的一种架构风格 。罗伊菲尔丁(Roy Fielding)于 2000 年在他著名的 ​​论文​​中首次提出它。

REST 没有强制执行任何关于它应该如何在较低级别实现的规则，它只是提出了高级设计指南，让我们考虑自己的实现。


符合 REST 架构风格的 Web API（或 Web 服务）是 REST API。


标准

知识分享之规范——RESTful API规范_服务器

image.png

1.统一接口


一旦开发人员熟悉了您的一个 API，他应该能够对其他 API 遵循类似的方法。


通过将 ​​通用性原则​​应用于 组件接口，我们可以简化整个系统架构并提高交互的可见性。多个架构约束有助于获得统一的接口并指导组件的行为。

以下四个约束可以实现统一的 REST 接口：

  • [资源标识] 所请求的资源可识别并与发送给客户端的表述分离开。
  • [通过表述操作资源] 客户端可通过接收的表述操作资源，因为表述包含操作所需的充足信息。
  • [自描述消息] 返回给客户端的自描述消息包含充足的信息，能够指明客户端应该如何处理所收到的信息。
  • [超媒体作为应用程序状态的引擎 ] 超文本/超媒体可用，是指在访问资源后，客户端应能够使用超链接查找其当前可采取的所有其他操作。

2. 客户端-服务器


服务器和客户端也可以更换和独立开发，只要不改变它们之间的接口即可。


3.无状态


在请求之间，不应将客户端上下文存储在服务器上。客户端负责管理应用程序的状态。


4. 可缓存


管理良好的缓存部分或完全消除了一些客户端-服务器交互，进一步提高了可伸缩性和性能。


5.分层系统


REST 允许您使用分层系统架构，例如，在服务器 A 上部署 API，在服务器 B 上存储数据并在服务器 C 中验证请求。客户端通常无法判断它是直接连接到终端服务器还是中间连接。


6.按需编码（可选）


上述所有约束都可以帮助您构建真正的 RESTful API，您应该遵循它们。不过，有时，您可能会发现自己违反了一两个约束条件。别担心; 你仍在制作一个 RESTful API——但不是“真正的 RESTful”。


规范应用于实际案例：

/devices
/devices/{id}

/configurations
/configurations/{id}

/devices/{id}/configurations
/devices/{id}/configurations/{id}


请注意，这些URI 不使用任何动词或操作。不要在 URI 中包含任何动词，这一点至关重要。URI 应该都是名词。


日常我们进行各种各样的增删改查，规范中推荐如下HTTP请求方式进行提供相关接口：

GET 查询、POST创建、PUT更新、DELETE删除、

REST API 使用HTTP 响应消息的状态行部分来通知客户端其请求的总体结果。​​RFC 2616​​​定义了​​Status-Line 语法​​，如下所示：


状态行 = HTTP 版本 SP 状态代码 SP 原因短语 CRLF


HTTP 定义了这些标准状态代码，可用于传达客户端请求的结果。状态码分为五类。

​​详细状态码请查看这里​​

本文声明：

知识分享之规范——RESTful API规范_超媒体_02

88x31.png


​​知识共享许可协议​​

本作品由 ​​cn華少​​ 采用 ​​知识共享署名-非商业性使用 4.0 国际许可协议​​ 进行许可。