RESTful API 设计规范

修改记录

什么是 REST？

REST（Representational State Transfer，表现层状态转换）这一概念最早于 2000 年出现于 Roy Fielding 的博士论文中，是一种 WEB 应用软件架构风格，其目标是便于不同的软件/程序在网络中互相传递信息。其是基于 HTTP 协议（兼容现代 HTTPS 协议）构建的一组约束和属性，旨在提供 WEB 应用程序构建风格。

设计要点

基本原则

1. 资源均由 URL 指定
2. 对资源的操作有四种：获取、创建、修改和删除，这分别对应 HTTP 协议中的四种方法：GET、POST、PUT、DELETE。
3. 通过操作资源的表现形式来操作资源。
4. 资源的表现形式则是XML或者HTML，取决于读者是机器还是人，是消费web服务的客户软件还是web浏览器。当然也可以是任何其他的格式，例如JSON。

风格特征

接口统一

1. 以资源为基础

   每个资源都可以通过 URI 访问到，即任何可用的资源均能通过唯一确定的 URI 访问。

2. 通过重表达的客户端可以管理原资源

   这也就是我们使得表现层“状态转换”的实质。

3. 返回信息足够描述自己

   这使得任何客户端请求任意 API 的时候都知道如何处理翻回信息。

4. 超媒体是应用状态的引擎

   这意味着遵循 RESTful API 风格的设计需要满足并具有无状态、可缓存、客户端-服务端架构、分层架构的特性。

约束条件

一个满足 RESTful API 设计风格的程序需要满足以下约束：

1. CS架构
2. 无状态（每个请求中包含所有需要的信息，服务端不能保存客户端的状态，但可以通过 Token 等方式实现用户状态的追踪）
3. 可缓存
4. 统一接口
5. 分层系统
6. 按需代码（程序需要可以通过直接添加可执行代码的方式进行拓展）

具体设计方法

传统方法

RESTful API 风格要求我们从三个方面定义一个资源：

• 一个直观简短的资源地址（通常为主机地址+资源名词）
• 对传输资源的描述
• 对服务器资源进行的操作（如 GET/POST/PUT/DELETE）

在具体实现中，我们应避免在资源地址中引入动词，从而避免不同 API 的语义混乱。对于用户状态的保留问题，我们不应也不能在服务端对用户状态进行存储，而应该通过 token 等的验证方式使得 API 访问传输的数据中带有加密的验证信息来证明客户端身份。另一方面，我们无需在传输开始前进行额外的加密，而应通过 HTTPS 的方式确保数据安全，这样使得我们可以在客户端和服务端进行数据有效性的双重校验。

历史问题

• 是否应该使用 PUT 和 DELETE 方法？为什么 PUT 和 DELETE 方法似乎不常用？

  我们的建议是：在需要使用的时候，尤其是确保您的浏览器支持的情况下，无需规避使用这两种方法，从而避免引入语义混乱的资源地址。早期不使用 PUT 和 DELETE 方法的原因主要是 HTTP 协议没有提供任何对于安全性（Security）的保证，而这两个方法对数据安全性的影响甚大。另一方面，早期浏览器不支持 PUT 或 DELETE 方法，使得服务端经常无法正常响应请求。随着 HTML5 的推广，主流浏览器（Firefox/Chrome/Edge）均已经支持包含 PUT 和 DELETE 在内的所有 HTTP Methods，这点问题已经无需担心。同时通过 HTTPS 和 token 等技术的确保，安全性也已经不再成为问题。现在您可以看到包括 Google 和 Github 在内的大多数公司都已经使用包含这两个方法的 API 设计作为某些服务的接口，尽管这主要仍停留在非浏览器服务的范畴。