什么是RESTful API？

RESTful API 是一种符合 REST 的设计原则或具象状态传输 架构风格的 API，又称为REST API。简单的说，REST就是客户端按照约定向服务端请求指定数据、或者在服务端保存数据，服务端响应客户端请求的过程。

什么是RESTful？

RESTful单独使用时，可以理解为‘符合REST的’，因此理解REST定义即可。
一般用法‘RESTful API、RESTful Architecture’等。

什么是REST？

REST是一种软件架构，决定了 API 的工作条件。2000年，罗伊·菲尔丁提出了代表状态转移（REST）作为设计网络服务的架构方法，REST 最初作为管理复杂网络（例如互联网）上的通信的指南而建立。使用者可以使用基于 REST 的架构为高性能和可靠的大规模通信提供支持；可以轻松应用和修改此种架构，为任何 API 系统带来可见性和跨平台可能性。

REST架构是一种基于超媒体构建分布式系统的建筑风格，它独立于任何底层协议，不一定与HTTP绑定，唯一的要求是它们要符合以下六种 架构约束(架构约定)：

1. 统一接口。 无论请求来自何处，对同一资源发出的所有 API 请求都应该看起来相同。 REST API 应确保同一条数据（例如用户的姓名或电子邮件地址）仅属于一个统一资源标识符 (URI)。 资源不应过大，但应包含客户可能需要的每一条信息。
   
2. 客户端/服务器解耦。 在 REST API 设计中，客户端和服务器的应用程序必须彼此完全独立。 客户端应用程序应该知道的唯一信息是所请求资源的 URI；它不能以任何其他方式与服务器应用程序交互。 同样，除了通过 HTTP 将客户端应用程序传递到所请求的数据外，服务器应用程序不应修改客户端应用程序。
   
3. 无状态。 REST API 是无状态的，这意味着每个请求都需要包含处理它所需的全部信息。 换句话说，REST API 不需要任何服务器端会话。 不允许服务器应用程序存储与客户端请求相关的任何数据。
   
4. 可缓存性。 如果可能，资源应该可以在客户端或服务器端缓存。 服务器响应还需要包含有关是否允许对交付的资源进行缓存的信息。 目标是提高客户端的性能，同时增强服务器端的可扩展性。
   
5. 分层系统架构。 在 REST API 中，调用和响应都会经过多个不同的层。 根据经验，不要假设客户端和服务器应用程序直接连接到彼此。 通信环路中可能包含多个不同的中介服务器。 需要设计 REST API，让客户端和服务器都无法判断它是与最终应用程序还是中介服务器进行通信。
   
6. 按需编码（可选）。 REST API 通常发送静态资源，但在某些情况下，响应也可以包含可执行代码（例如 Java 小程序）。 在这些情况下，代码只应按需运行。

简而言之，在REST架构风格中，数据和功能被视为资源，并使用统一资源标识符（URI）进行访问。

什么是REST API？

一般情况下，遵循 REST 架构风格的 API 称为 REST API。
因为REST 是一组架构规范，并非协议或标准，API 开发人员可以采用各种方式实施 REST。例如，当客户端通过 REST API 提出请求时，它会将资源状态表述传递给请求者或终端。该信息或表述通过 HTTP 以下列某种格式传输：JSON（Javascript 对象表示法）、HTML、XLT、Python、PHP 或纯文本。

由于JSON 能被人和机器‘读’，在当下开放API环境及大部分企业内部应用中，实施REST API时，默认都采用REST约定+HTTP+JSON，这种组合已经是一种事实上的标准。 下文及本网站提到的REST API、[[wiki:http-api|HTTP API]、Web API，在具体实施时，一般都是‘REST约定+HTTP+JSON’标准的API。

需要注意的地方： RESTful API采用HTTP时，HTTP头和参数、 HTTP 方法也很重要，因为其中包含了请求的元数据、授权、统一资源标识符（URI）、缓存、cookie 等重要标识信息。有请求头和响应头，每个头都有自己的 HTTP 连接信息和状态码。在《RESTfal API 设计》一文中会重点讲这部分内容的设计。

REST API使用的一些基本概念：

✅ REST API – Payload
✅  REST API – HTTP Methods
✅  REST API – HTTP Status Codes

什么是RESTful API？

RESTful API就是REST API，术语 REST API 和 RESTful API 可以互换使用。

理解”统一接口”原则

统一接口是一切 RESTful Web 服务设计的基础。其表示服务器以标准格式传输信息。格式化的资源在 REST 中称为表征。此格式可以与服务器应用程序上资源的内部表征不同。例如，服务器可以将数据存储为文本，但以 JSON 表征格式发送该数据。

统一接口强制实施四个架构约束：

1. 请求应确定资源。它们通过使用统一的资源标识符实现此功能。
2. 客户端包含资源表征中的足够信息以修改或删除资源（如需要）。服务器通过发送进一步描述资源的元数据以符合这一条件。
3. 客户端接收有关如何进一步处理表征的信息。服务器通过发送自描述信息实现此功能，该信息包含了有关客户端如何以最佳方式使用这些信息的元数据。
4. 客户端接收有关其完成任务需要的所有其他相关资源的信息。服务器通过在表征中发送超链接实现此功能，以便客户端可以动态发现更多资源。

理解REST资源概念

REST中信息的关键抽象是一个资源。我们可以命名的任何信息都可以成为一种资源。例如，REST资源可以是文档或图像、时间服务、其他资源的集合或非虚拟对象（例如一个人）。
在任何特定时间，资源的状态都被称为资源表示。资源表示包括：

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

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

1)资源标识符

REST使用资源标识符来识别客户端和服务器组件之间交互中涉及的每个资源。

2)超媒体

表示的数据格式被称为媒体类型。媒体类型标识了一个规范，该规范定义了如何处理表示。

RESTful API看起来像超文本。每个可寻址信息单元都携带一个地址，要么显式（例如，链接和id属性），要么隐式（例如，从媒体类型定义和表示结构派生）。

3)自我描述

此外，资源表示应是自我描述的：客户不需要知道资源是员工还是设备。它应该根据与资源相关的媒体类型进行操作。
因此，在实践中，我们将创建许多自定义媒体类型——通常与一个资源关联的一种媒体类型。
每种媒体类型都定义了默认处理模型。例如，HTML定义了超文本的渲染过程和围绕每个元素的浏览器行为。

如何描述REST API？

REST API是随着互联网SAAS业务的发展而兴盛，开放API给更多的人使用是其核心目标之一，2011年由SmartBear Software的首席执行官Dann Milner提出OpenAPI描述，逐步发展为一套REST API描述规范（它类似SOAP的描述规范WSDL）。
Open API描述规范 为REST API on HTTP提供了一个正式的标准，它使用YAML或JSON格式，描述API的路径、参数、请求和响应的结构、错误码等信息。
JSON格式示意：

{
	"title": "Sample Pet Store App",
	"description": "This is a sample server for a pet store.",
	"termsOfService": "http://explinks.com/terms/",
	"contact": {
		"name": "API Support",
		"url": "http://www.explinks.com/support",
		"email": "support@example.com"
	},
	"license": {
		"name": "Apache 2.0",
		"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
	},
	"version": "1.0.1"
}

YAML格式示意：

title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://explinks.com/terms/
contact:
  name: API Support
  url: http://www.explinks.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

由于 OpenAPI 描述是计算机可读的，因此可以使用它来执行如下操作：

• 生成库以方便使用 REST API
• 验证并测试使用 REST API 的集成
• 使用第三方API设计工具（如 Postman）探索 REST API 并与之交互。

如何设计REST API？

REST API的架构约束理解起来很容易，设计起来灵活度很大，以下是一些主要设计原则：

• REST API是围绕资源设计的，这些资源是客户端可以访问的任何类型的对象、数据或服务。
• 资源有一个标识符，这是一个唯一标识该资源的URI。例如，特定客户订单的URI可能是：https://adventure-works.com/orders/1
• 客户通过交换资源表示与服务交互。许多Web API使用JSON作为交换格式。例如，对上面列出的URI的GET请求可能会返回此响应主体：{"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}
• REST API使用统一的接口，这有助于将客户端和服务实现解耦。对于基于HTTP构建的REST API，统一接口包括使用标准HTTP动词对资源执行操作。最常见的操作是GET、POST、PUT、PATCH和DELETE。
• REST API使用无状态请求模型。HTTP请求应该是独立的，并且可以以任何顺序发生，因此在请求之间保留瞬态状态信息是不可行的。存储信息的唯一地方是资源本身，每个请求都应该是一个原子操作。这种约束使网络服务具有高度可扩展性，因为不需要在客户端和特定服务器之间保留任何亲和力。任何服务器都可以处理来自任何客户端的任何请求。也就是说，其他因素可能会限制可扩展性。例如，许多Web服务写入后端数据存储，这可能很难扩展。
• REST API由表示中包含的超媒体链接驱动。例如，以下显示了订单的JSON表示。它包含获取或更新与订单关联的客户的链接。

但在具体操作中却比较复杂，网上有大量的API设计指导及规范，我们搜集、整理了一部分：
RESTful API 设计
RESTful API 实践之一
RESTful API 实践之二

如何评估REST API成熟度？

2008年，Leonard Richardson为Rest API提出了以下成熟度模型：

• 级别0：定义一个URI，所有操作都是对此URI的POST请求。
• 第1级：为单个资源创建单独的URI。
• 第2级：使用HTTP方法定义资源上的操作。
• 第3级：使用超媒体（HATEOAS，如下所述）。

根据Fielding的定义，第3级对应于一个真正的RESTful API。在实践中，许多已发布的Web API大约在2级左右。

REST API安全

REST API 安全也始于行业最佳实践，例如使用散列算法确保密码安全性，使用 HTTPS 实现安全数据传输。 像 OAuth 2.0这样的授权框架可以帮助限制第三方应用程序的特权。 使用 HTTP 头中的时间戳记，API 还可以拒绝在特定时间段后到达的任何请求。 同时也可以通过参数验证和 JSON Web 令牌等方式来确保只有经过授权的客户端才能访问 API。

参考资料：

架构风格与基于网络应用软件的架构设计（中文修订版）
10大REST API常见问题？
https://restfulapi.net
https://aws.amazon.com/cn/what-is/restful-api/
什么是API？(Aws)
REST与SOAP的区别？
介绍 Web 基础架构设计原则的经典论文《架构风格与基于网络的软件架构设计》导读