RESTful API 规范

REST 和 RESTfulAPI

REST是REpresentational State Transfer表述性状态转移 的首字母缩写，是一种基于超媒体构建分布式系统的架构风格。与其他架构风格一样，REST有其指导原则和约束。如果接口设计时需要引用RESTful API 规范，则必须满足这些原则。

REST的指导原则

• 客户端 - 服务器 : 通过将用户接问题与数据存储问题分开，通过简化服务器组件来提高跨多个平台的用户接口的可移植性并提高可伸缩性。

• 无状态 : 从客户端到服务器的每个请求都必须包含理解请求所需的所有信息，并且不能利用服务器上任何存储的上下文。因此，会话状态完全保留在客户端上。

• 可缓存 : 缓存约束要求将对请求的响应中的数据隐式或显式标记为可缓存或不可缓存。如果响应是可缓存的，则客户端缓存有权重用该响应数据以用于以后的等效请求。

• 统一接口 : 通过将通用性的软件工程原理应用于组件接口，简化了整个系统架构，提高了交互的可见性。为了获得统一的接口，需要多个架构约束来指导组件的行为。REST由四个接口约束定义：

  • 资源识别 : 接口必须唯一标识客户端和服务器之间交互中涉及的每个资源。
  • 通过陈述来处理资源 : 资源应该在服务器响应中具有统一的标识。API 使用者应该使用这些标识来修改服务器中的资源状态。
  • 自我描述性的信息 : 每个资源标识应该携带足够的信息来描述如何处理消息。它还应该提供客户端可以对资源执行的附加操作的信息。
  • 超媒体作为应用程序状态的引擎 : 客户端应该只有应用程序的初始 URI。客户端应用程序应使用超链接动态驱动所有其他资源和交互。

• 分层系统 :分层系统风格允许通过约束组件行为来使体系结构由分层层组成，这样每个组件都不能“看到”超出与它们交互的直接层。

• 按需编码（可选） - REST允许通过以小程序或脚本的形式下载和执行代码来扩展客户端功能。这通过减少预先实现所需的功能数量来简化客户端。

资源与资源方法

资源

• REST中信息的关键抽象是一种资源。可以命名的任何信息都可以是资源：文档或图像，临时服务，其他资源的集合，非虚拟对象（例如，人）等。

• REST使用资源标识符来标识组件之间交互中涉及的特定资源。

• 资源在任何特定时间的状态称为资源表示。资源主要包括：

  • 数据
  • 描述数据的 元数据
  • 可以帮助客户过渡到下一个所需状态的 超媒体链接。

• REST API 由一组相互链接的资源组成。这组资源称为 REST API 的 资源模型。

• 资源表示应该是自描述的：客户端不需要知道资源是员工还是设备

资源方法

• 与 REST 相关的另一个重要事情是 资源方法。这些资源方法用于在任何资源的两种状态之间执行所需的转换。
• 将资源方法与HTTP GET / PUT / POST / DELETE方法联系起来是错误的。
• 基于查询的API结果应该由带有摘要信息的链接列表表示
• REST和HTTP不一样!! REST是一种架构设计风格，而非是HTTP规定的协议。

RESTful API的特点

• 客户端在通过 API 与后端服务通信的过程中，建议使用 HTTPS 协议。

• API 的根入口点应尽可能保持足够简单。

• 使用 - 而不是使用 _ 做URL路径中字符串连接。

• 使用Token令牌来做用户身份的校验与权限分级，而不是Cookie。

• 在 URL 中嵌入版本编号时所有的 API 必须保持向后兼容，你必须在引入新版本 API 的同时确保旧版本 API 仍然可用。

• 特定资源或资源集合的 URL在设计时必须遵循以下约定：

  • HTTP 动词作用的对象。它应该是名词，不能是动词。
  • URL 的命名 必须 全部小写
  • URL 中资源（resource）的命名 必须 是名词，并且 必须 是复数形式
  • 必须 优先使用 Restful 类型的 URL
  • URL 必须 是易读的
  • URL 不能暴露服务器架构
  • 避免多级 URL，这种 URL 不利于扩展，语义也不明确，查询字符串的写法会更好。

• 对于资源的具体操作类型，由 HTTP 动词表示。常用的 HTTP 动词有下面五个：

  • GET（SELECT）：从服务器取出资源（一项或多项）。
  • POST（CREATE）：在服务器新建一个资源。
  • PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  • DELETE（DELETE）：从服务器删除资源。

• 如果记录数量很多，服务器不可能都将它们返回给用户。API 应该 提供参数，过滤返回结果。下面是一些常见的参数：

  • ?limit=10：指定返回记录的数量
  • ?offset=10：指定返回记录的开始位置。
  • ?page=2&per_page=100：指定第几页，以及每页的记录数。
  • ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
  • ?animal_type_id=1：指定筛选条件

• 所有的 API 响应，必须 遵守 HTTP 设计规范，必须 选择合适的 HTTP 状态码。下面列举了常见的 HTTP 状态码（所有 API 一定不可 返回 1xx 类型的状态码）

  • 1xx 代表请求已被接受，需要继续处理
  • 2xx 请求已成功，请求所希望的响应头或数据体将随此响应返回
  • 3xx 重定向
  • 4xx 客户端原因引起的错误
  • 5xx 服务端原因引起的错误

• 返回结果必须使用JSON， 必须把错误信息直接放到响应实体中，并且错误格式 应该 满足如下格式：

    {
        "message": "您查找的资源不存在",
        "error_code": 404001
    }
  

总结

• 在REST架构风格中，数据和功能被视为资源，并使用统一资源标识符（URI）进行访问。
• 通过使用一组简单，定义明确的操作来执行资源。
• 客户端和服务器通过使用标准化接口和协议（通常是HTTP）来交换资源的表示。
• 资源与其表示分离，以便可以以各种格式访问其内容，例如HTML，XML，纯文本，PDF，JPEG，JSON等。例如，可以使用和使用关于资源的元数据来控制高速缓存，检测传输错误，协商适当的表示格式，以及执行认证或访问控制。
• 最重要的是，与资源的每次交互都是无状态的。

相关链接

• RESTful官方文档
• SOAP与REST API的区别
• RESTful API 设计规范

这篇好文章是转载于：学新通技术网