共计 4199 个字符，预计需要花费 11 分钟才能阅读完成。
| 导读 | 在本文中，我的目标是向大家尽可能详细的解释 REST API，包括理论和开发部分。以便大家能清楚的了解何时用以及如何使用它，包括它的本质是什么。无论是自己开发 API 还是使用第三方 API，都会更加顺利。 |
像 Alibaba,Baidu,Tecent,Toutiao，Facebook,Google,Amazon 等公司都拥有开放的 RESTful API 或开放，我们可以申请访问，获取甚至写入数据。
所有的事情都要问为什么。为什么需要 REST API？REST 为何如此普及？
当然，传递信息有很多种方式。如 Socket，REST，WebService，HTTP 等。
REST 很灵活，与 HTTP 协议兼容。它是一个架构风格，并非标准，用它来提供各种服务，可以用各种编程语言来实现。
在本篇文章中，我们的目标是一起清晰的了解 REST，知道何时用以及如何使用它，以及 REST 的本质。
我们将通过一些基础知识和定义，包括 REST API 的最佳实践，可以让各位能够用任何开发语言来实现 REST API。
建议您有 HTTP 协议基础，或者了解一部分，可以充分消化这部分内容。
REST – Representational State Transfer 是 Roy Field 博士创立的一种架构风格，他在 UC Irvine 的论文中描述了架构风格与基于 Web 的软件架构设计，并使用 HTTP 1.1 开发。
我们使用 REST 做为互联网上不同计算机系统间通信的一种方式。
REST 绑定 HTTP
根据 REST 定义，并非如此。尽管人们可以使用其它一些 REST 应用程序协议，但在涉及 REST 实现时，HTTP 仍然是应用程序协议中无可争辩的主流。
RESTful 有下列一些特点：
1、客户端 / 服务器架构：完整的服务由前端“客户端”和整个系统的后端“服务器”组成。
2、无状态：服务器在不同请求中间不保存任何状态。会话的状态完全由客户端负责。根据 REST 的定义：所有 REST 交互都是无状态的，也就是说，每个请求都包含连接器理解请求所需的全部信息，而不受任何先前可能发生的请求影响。
3、可缓存：客户端应该能够将响应存储在缓存中，以便获得更好的性能。
RESTful API 遵循以上这些规则，并使用 HTTP 方法来操作资源集的服务。
因为它们提供了一种简单、灵活和可扩展的方式来开发 Web 通信的分布式应用程序。
我们可能有很多 REST API。如果业务足够广，需要开放的服务也会变得复杂。
开发者需要一些实用主义才能做出好的应用和服务。
理论对于认知理解很重要，但理论的实施才是区分优劣应用差异的检验标准。为此，我们要聪明的工作，但一定要记得，最终用户才是第一优先级，是最高价值。
我们知道了重点，让 API 做得强大易，让用户的工作也变得更容易。
在开发软件时，我们会经常使用面向对象的抽象和多态来开发应用程序。这样可以最大化重用代码。
那么，我们是不是也应该这样开发 REST API？
到开发 API 的情况就不同了，对于 REST API，具体比抽象更好。也就是完成实际的功能更好。我们来看一些实例：
有两个 api 版本：
您做为开发者，哪个描述会更清楚，您愿意用哪个 API？我选择第二个。
URI 格式，使用名词而非动词
下面是 API 开发的另一个最佳实践。我们如何格式化你的结点？如果你使用编码的方法来命名 URI 结点，会是以下的结果：
我想您已经明白，这会有很多个 URL 结点，每个结点只做一件事情。
我们要有一个更系统的命名来精简梳理上面这个摊子。先把资源用名词来描述，把 HTTP 方法换成动词。于是我们会得到下面这样的结果：
这样，一个更简洁，精确的 API 就出现了。对于使用的用户来讲，他会马上清楚。当然，你可以使用单数形式而不是复数形式，这样显得资源名称更为整洁，您根据自己的喜好，这点取决于自己。
本阶段是 API 开发的另一个重要方面。有好几个很好的方法来处理错误。
我们来看一些高级的开发狗是咋干的：
请求：GET https://api.twitter.com/1.1/account/settings.json
响应：状态码 400
{"errors":[{"code":215,"message":"Bad Authentication data."}]}Twitter 给我们的状态码和错误码，以及一个简短说明。
请求：GET https://graph.facebook.com/me/photos
响应：状态码 400
{
"error": {
"message": "An active access token must be used to query information about the current user.",
"type": "OAuthException",
"code": 2500,
"fbtrace_id": "DzkTMkgIA7V"
}
}Facebook 给够给你一个更具体的错误信息。
请求：GET https://api.twilio.com/2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234
响应：状态码 404
<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
<RestException>
<Code>20404</Code>
<Message>The requested resource /2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 was not found</Message>
<MoreInfo>https://www.twilio.com/docs/errors/20404</MoreInfo>
<Status>404</Status>
</RestException>
</TwilioResponse>Twilio 给我们一个 XML 响就格式，并且能够链到你能找到错误细节的文档。
我们看到，不同的开发者提供方法存在一些区别。但是这些开放平台都提供了具体的错误信息，不会只简单告诉用户不可用，让用户不知道发生了什么，让他们在搜索引擎无目的的搜索只会浪费时间。
在设计 REST API 时，需要使用 HTTP 状态代码与 API 进行通信。
如你所想，HTTP 有很多现成状态码，可以描述一些可能的响应。
但是，我们应该用多少？我们应该对每一种情况都有严格的状态编码么？
HTTP 状态码超过 70 个状态，你知道他们的核心吗？API 用户是否会用到它们，避免让大家再去查。我们大多数都熟悉以下的状态码：
我们先从这三点开始，来逐步覆盖 REST API 的大部分功能。
其它常见的状态码：
可以通过功能帮助用户快速找出结果。如果觉得状态代码不够在错误处理显示描述性内容，那么应该包含某类型的消息。再通过代码和描述性信息来帮助 API 用户。
REST API 安全性依赖于标准的 HTTP 机制，如基本认证或摘要认证。
每个请求都应该通过 HTTPS 进行。
提高 REST API 的安全性有很多技巧，但是由于 REST 的无状态特性，在实现它们时请务必小心谨慎。比如最后一个请求的状态未返回，客户端应该存储和验证状态。
另外，使用时间戳和记录请求对我们也有很大帮助。
关于此话题还有很多要说的，但不在本文的讨论范围内。如果您想了解更多关于 HTTP 安全的信息，请查阅 21CTO 公众号或社区网站。
我们已经编写了 REST API，许多用户已经用上了它，我们对此感到满意。
但是出现了新功能，需要增加或修改原有功能和方法，有可能还是很大的变化。
不必担心，我们有解决方案。
在开始开发 API 之前，我们可以通过将 API 版本前添加到 URI 端点，以此达到 API 版本化。如下：
https://api.21cto.com/v1/authors/2/blogposts/13
这样，只要 API 发生重大变更，就可以随时增加 API 版本号（比如，v2，v3 …）。这也向用户发出信号，说明一些重要的变化，使用新版本时应该小心。
这是一个简而易见的方法。您可能是世界上最好的 API 开发者，但如若没有文档，API 就失去一半的生命力。
正确完整的文档对于每个软件产品和 Web 服务都至关重要。
当然，您当然可以通过保持一致并使用清晰的描述性语法来让用户很容易的学习。但是，好的文档仍然不可或缺。
以下是一些开放平台 API 的文档例子：
https://www.twilio.com/docs/api/rest/
https://developers.facebook.com/docs/
https://developers.google.com/maps/documentation/
有很多工具可以我们开发和调试 API，但是不要忘了添加人的测试和理解，让一个人可以正确理解您的思维。
我们在本文了解了构建 REST API 的概念，并介绍了一些 REST API 的最佳开发实践。如果您第一次尝试开发自己的 REST API。可以尝试在本文中的 REST API 最佳实践。
先从最小的 API 开始，遵循这几个实践，相信您会成就感满满。
后面我们有一个持续的系列文章，展示相关语言开发实践。比如您是 C# 或者 Java 专家，了解如何以几种不同的方式使用 RESTful API。
我还错过了什么内容吗？如果您知道还有更重要的，欢迎在本文底部发表评论~
