你的数据模型已经开始稳定，这样你就可以为你的 web app 或者你的设备创建一个公开的 API。

你意识到一旦发布，你想要改变你的API就很难了，所以想要做更多正确的事，就要尽可能早地做工作。现在，互联网不缺乏 API 的设计意见。

但是因为没有一个广泛采用的标准，在大多数情况下，你都会有一大堆选择：你应该接受什么格式？如何进行身份验证？你的 API 应该版本化吗？

让我们先从基本的向导开始吧......

什么是REST?

表述性状态转移(REST)是描述万维网如何运行的专业术语.。假设互联网是一台设备，如果它有一个操作系统，那么它的操作系统的架构便是REST。一个REST应用程序编程接口（即REST API）是一类网络服务，该服务允许用户操作或者自动化客户端访问管理系统数据和功能的资源。经过精心设计的REST API会引导开发者使用网络服务，并且这是当下必备的一个特性。但是如何准确地定义API是否符合REST的规范呢？REST架构描述了6个约束,下面我们将对它们进行具体介绍.

规范统一的接口

规范统一的接口要求任何REST服务必须得提供一个符合其设计的基础规范。

其限定规则对客户端和服务端之间的接口进行了定义。对于规范统一的接口有四个指导原则：

• 基于资源: 独立的资源都是在请求中使用URI作为资源的标识符来进行定义的，而且在返回给客户端的响应那里进行了分离。

• 通过接口所呈现的数据来决定对资源进行什么样的操作: 当客户端获取到了一个资源的数据呈现，包含一些附带的元数据，它也就有了足够的信息来对服务器上的资源进行定制或者删除操作，前提是它有这样做的权限。

• 具备自我描述性的信息: 每一个消息都包含了一块能精确描述如何对齐进行处理的信息。响应信息也会清晰明确的指出它们是否具备缓存能力。

• 将超媒体作为应用程序状态的引擎 (HATEOAS): 客户端会通过消息体内容、查询字符串参数、请求消息头还有请求的URI来传递状态信息。服务会通过消息体内容、响应编码以及响应消息头来先客户端传递状态。

客户端-服务端

客户端和服务端被规则的接口分离开来。比如，客户端不关心数据存储，数据存储由每个服务端维护，这提高客户端代码的可移植性。服务端不用操心用户界面或者用户状态，所以可以变得更简单，更具伸缩性。只要接口不变，服务端和客户端都可以独立的替换或升级。最重要的事情是有完整的接口——可以给客户端一个在线 REST API 文档或者REST API模拟调用用以帮助客户端开始连接。

无状态的

URL、查询参数、内容或者头中已经包含了操作请求所需要的各种状态。URL标识资源，内容包含了资源的状态。然而，服务端处理之后，适当的状态或部分状态会通过响应头、响应状态、响应内容等回传给客户端。

可缓存的

客户端可以缓存响应，这需要隐式或显式的定义为可缓存的，或者在将来的请求中不阻止客户端重复使用状态，或者允许不太合适的响应数据。一个管理良好的缓存会排除一些，甚至全部客户端与服务端之间的活动，以提升性能。

微服务

微服务或者分层次系统使得客户端在请求时通常不能够知晓它是直接连接到最终的服务器还是一个中间服务器。使用负载均衡和一致性缓存的调解服务或API网关，有助于提高系统可扩展性，分层系统也能强化安全策略。
 

按需编码

服务可以通过传输执行命令进行临时扩展或者实现自定义功能。以使用的编译组件为例，编译组件可能包括：Java applets编译器和用户端的脚步语言（例如JavaScript）的编译器，随需而定。按需编码是六个约束中唯一一个可选项。

版本化

获得 RESTful 版本权限主要会影响 API 用户对 API 的内部及外部的感知方式，如果不加注意，还会给 API 的管理带来困扰。

因此，版本是指导的重要组成部分，或许，它对于在组织中建立一套完善的政策更加重要。因为团队模式的独立性，如果所有的团队都采取不同的管理方法，那么，在整个组织中想要管理好 API 间的相互依赖就会变得非常困难。

因此，一个版本的政策的定义，应贯穿整个组织，且指导内容的条理要清晰，要说明 API 版本使用的时间及原因。同时，要保证团队的灵活性，允许成员以他们认为合适的方式执行版本的要求（自定义头部，接收头部或者作为 URI 的一部分。）

REST API 的构建块:

如下可能是一个API最重要的几个基础构建块:

• 资源(URI)

• HTTP 方法

• HTTP 消息头

• 查询参数

• 返回编码

任何看到这个五个部分且自身又是HTTP和REST API领域专家的人，可能会争辩道这些都是为特殊目的而设计的，并且应该清楚地考虑只让它们被用于这些目的。

不过，很有可能许多为你创建API的开发者不会了解(而且在某些情况下也并不很在意)REST的分别和基本原则。

这份同时面向开发者和你的客户(不过主要的指导方法都是面向开发者的)的指南或者说REST风格的API 文档，其作用是详细阐述如何利用这里面的每一条: 它会对需要设置限制的翻译进行了限制。举个指南集合的例子:

• 资源应该是描述你的API所描述的“对象”，以一个单独标识每个对象的标识符。

• HTTP 方法被用来“改变”对象的状态, 附带要有一个规定的方法的授权列表。

• HTTP 消息头被用来传递必要的参数，比如认证信息，可接受的内容类型等。

• 查询参数被用于可选参数或者过滤（搜索），并且可以根据需要被省略掉。

• 返回的编码需要能映射核心HTTP规范的意思和语义, 要确保编码携带的信息足够丰富，并且在必要时带上一些额外的信息。

这些指南的提出是为所有的开发者明确如何对待这些构造类型中的每个个体: 对他们的用途及执行方法做出定义。

更加具备限制性的指南会深入到诸如具体的资源构造已经被允许使用的HTTP消息头, 因而留给开发者心中的疑问会更少。

总言之，除了所需要的代码，任何违反了约束都意味着那个服务算不上RESTful。遵守所有的约束而因此符合REST的架构，就能够让任何类型的分布式超媒体系统拥有意想不到的特性，比如高性能，可扩展性，简洁性，可修改性，美观性，可移植性以及可靠性。