什么是REST API

当前的应用中，REST API调用的应用越来越多，这里介绍什么是REST API，RESTFUL设计原则与规范，以及与SOAP与HTTP的区别.

API

API = Application Programming Interface

API（Application Programming Interface，应用程序接口）是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的约定。 用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机的细节[1]。

API接口可分为两类：本地API接口，如操作系统提供的API函数，应用程序提供库，用于其他用户调用相应的应用。网络API接口如RPC/SOAP/gRPC/REST等。

REST API

REST是Representational State Transfer词组的简写，即“表现层状态转化”。代表（互联网资源）表现层状态转化。最初由计算机科学家Roy Fielding博士在博士论文中于 2000 年定义。在这篇论文定义并详细介绍了表述性状态转移（Representational State Transfer，REST）的架构风格，并且描述了 如何使用 REST 来指导现代 Web 架构的设计和开发。用他自己的原话说：RESTful不是一个标准，但是一种规范。

1. 资源（Resources）

我们在互联网软件开发中，我们所说的“资源”是指在互联网中某一个节点的具体信息，如一段文本、一张图片、一个视频、一个压缩包、一个程序安装包等等。在互联网中，我们可以使用URI（统一资源定位符）来表示每一个具体的资源，因此，每一个互联网资源都一个独一无二的URI地址。

2. 表现层（Representational）

“资源”是一种信息的实体，实际上，资源有很多表现形成，如一段文本，我们可以使用普通的txt格式来表示，也可以用JSON格式来表示，还可以使用XML格式来表示。“资源”的具体表现形式我们就叫做表现层。在HTTP协议中，规定了头信息中的Content-Type字段来描述具体的资源表现形式。如“Content-Type: text/html”表示为html格式的文本数据，而“Content-Type: text/json”表示为JSON格式的文本数据。

3. 状态转化（State Transfer）

HTTP是一种无状态的网络协议，如果客户端要操作服务器，必须通过一种手段通知服务器进行“状态转化”，而这种状态改变建立在“表现层”之上，这就是“表现层状态转化”。在HTTP协议中，客户端通过发送相应的请求告知服务器实现某种状态的改变。客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作。

RESTFUL设计原则

统一界面

无论请求来自何处，对同一资源的所有 API 请求都应该看起来相同。 REST API 应确保同一条数据（例如用户的姓名或电子邮件地址）仅属于一个统一资源标识符 (URI)。资源不应太大，但应包含客户可能需要的每一条信息。

C-S解耦

在 REST API 设计中，客户端和服务器应用程序必须彼此完全独立。客户端应用程序应该知道的唯一信息是所请求资源的 URI；它不能以任何其他方式与服务器应用程序交互。同样，除了通过 HTTP 将客户端应用程序传递给请求的数据之外，服务器应用程序不应修改客户端应用程序。
无状态

 REST API 是无状态的，这意味着每个请求都需要包含处理它所需的所有信息。换句话说，REST API 不需要任何服务器端会话。不允许服务器应用程序存储与客户端请求相关的任何数据。
可缓存性

如果可能，资源应该可以在客户端或服务器端缓存。服务器响应还需要包含有关是否允许对交付的资源进行缓存的信息。目标是提高客户端的性能，同时增加服务器端的可扩展性。
分层系统架构

在 REST API 中，调用和响应经过不同的层。根据经验，不要假设客户端和服务器应用程序直接相互连接。通信回路中可能有许多不同的中介。需要设计 REST API，以便客户端和服务器都无法判断它是与最终应用程序还是中介进行通信。
按需编码

REST API 通常发送静态资源，但在某些情况下，响应也可以包含可执行代码（例如 Java 小程序）。在这些情况下，代码应该只按需运行。

RESTFUL 规范

URL 
    https://api.example.com 尽量将API部署在专用域名
版本

   将API的版本号放入URL，如：https://api.example.com/v1/     https://example.org/api/v1/

   或者放在accept 头部；

路径
     对于资源，均使用名词表示（可复数），对于不同的资源，都有一个唯一的URL地址，每一个

     URL地址代表一种资源，所以网址中应当是名称，如：

     https://api.github.com/orgs/:org/projects
     在上面URL中，orgs代表组织集合，而:org代表集体的组织名，projects代表具体的资源

协议：

     Https 或Http

操作：

     POST，表示为：创建和修改操作；

     GET，表示为：查询操作；

     PUT，表示为：修改操作；

     PATCH ，表示为：修改操作；

     DELETE，表示为：删除操作；

状态码

    API返回响应时，提供状态码。

    1XX: 表示正在进行；

    2XX: 表示成功；

    3XX: 表示重定向；

    4XX: 客户端出错；

    5XX: 服务器出错；

过滤

    通过在URL上传参的形式传递搜索条件
    https://api.example.com/v1/zoos?limit=10：指定返回记录的数量.

其他

SOAP与REST区别

SOAP (Simple Object Access Protocol) 顾名思义，是一个严格定义的信息交换协议，用于在Web Service中把远程调用和返回封装成机器可读的格式化数据。仅使用HTTP的POST方法，针对服务(URL标识）,使用XML定义操作来进行处理。例如：查询-post：URL  XML{动作：查询；资源：ID1}；删除-post：URL  XML{动作：删除；资源：ID1}。

REST可以使用HTTP的GET、POST、PUT、DELETE方法，针对资源（URI）操作。例如：查询-post：URL  ；删除-delete：URL。

REST相比SOAP更加简洁明了.

SOAP使用WSDL (Web Service Description Language) 也遵循XML格式，用来描述哪个服务器提供什么服务，怎样找到它，以及该服务使用怎样的接口规范，简言之，服务发现。

REST使用WASL(Web Application Description Language)来描述REST接口.

REST不是HTTP

由于 REST 也打算使网络（互联网）更加精简和标准，因此他提倡更严格地使用 REST 原则。这就是人们尝试将 REST 与 Web (HTTP) 进行比较的地方。 Roy fielding 在他的论文中没有提到任何实现指令——包括任何协议偏好和 HTTP。直到那时，您都遵守 REST 的 6 项指导原则，您可以将您的接口称为 RESTful。

简而言之，在 REST 架构风格中，数据和功能被视为资源，并使用统一资源标识符 (URI) 进行访问。通过使用一组简单的、定义良好的操作来处理资源。客户端和服务器通过使用标准化的接口和协议（通常是 HTTP）来交换资源的表示。

资源与其表示分离，以便可以以各种格式访问其内容，例如 HTML、XML、纯文本、PDF、JPEG、JSON 等。例如，有关资源的元数据可用并用于控制缓存、检测传输错误、协商适当的表示格式以及执行身份验证或访问控制。最重要的是，与资源的每次交互都是无状态的。

所有这些原则都有助于 RESTful 应用程序变得简单、轻量和快速。 

References:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm