RESTful%20API无处不在，比任何其他API体系结构都为现代世界提供了更多支持。%20根据ProgrammableWeb的研究，REST占API的80％。%20这些API的构建和结构方式可以在当今竞争异常激烈的世界中成败一家公司。%20设计不良的API可能难以使用，在最需要它们时可能会失败，并且是寻找敏感数据的黑客的重要目标。%20另一方面，利用最佳实践精心设计的API使开发变得轻而易举，吸引了新客户，并在用户之间建立了信心，从而可以提高保留率。

什么是RESTful%20API？

REST是REpresentational%20State%20Transfer的首字母缩写，描述了用于创建分布式Web服务的体系结构样式。%20REST允许用户使用标准的HTTP请求来远程调用代码并接收响应。%20REST与其他协议相比有几个优点：

·%20它将数据存储问题与用户界面分开，这意味着运行API的后端服务器可以处理所有逻辑以访问数据库并处理数据，然后再以统一的结构化方式将其返回给用户。%20这种一致的数据访问和结构使开发人员可以轻松构建前端应用程序，从而轻松地将您的应用程序前端移植到其他平台。

·%20REST%20API支持缓存常用的静态资源，以提高性能。

·%20REST是无状态的，因此完成请求的所有信息都包含在请求中。%20通过消除对服务器端状态同步逻辑的需求，这简化了API。%20这也使扩展变得更容易，因为任何服务器都可以处理任何请求而无需跟踪会话。

（如果构建RESTful%20API对您来说是新手，或者您希望沙盒尝试这些最佳实践，请从Heroku中尝试该参考体系结构，该体系结构易于部署。）

因此，现在，这是构建RESTful%20API的五种最佳实践。

1.使用错误状态代码

HTTP已经内置了100多个状态代码。使用RESTful%20API中的状态代码来传达一般错误对于开发人员来说是天赐的礼物。%20开发人员将能够立即发现问题，这意味着花费更少的时间编写解析器来处理所有不同类型的错误。%20是否因为会话未登录而拒绝了请求？%20有一个状态码。%20是否缺少资源？%20CRUD服务是否收到请求但无法连接到数据库？%20这些都有状态码，几乎还有其他常见行为。%20状态代码也可以与特定的错误消息结合使用，以提供有关失败请求的详细信息。

以下是Node.js%20API的一小段代码，用于说明：

该端点通过传入的用户ID返回用户配置文件。 响应请求而发送的状态代码可准确告知开发人员发生了什么错误，从而使响应更易于处理，并为他们节省了大量时间和麻烦。 开发人员可以根据状态代码实现用于处理不同错误的例程，而API提供详细的错误信息。 在这种情况下，404错误会告诉呼叫者找不到东西。 响应中的JSON会特别告诉调用者它是找不到的用户ID，而不是错误是指向端点还是请求的资源，这是模棱两可的。

2.好的文档

文档是API最重要（也是最被忽略）的方面之一。 正式文档可以是客户与产品的第一联系点，并且是开发团队是否采用该产品的关键因素。 好的文档看起来干净，一致，并为开发人员做好充分准备，使其可以快速使用您的API。 有人学习您的API的速度越快，他们开始使用它的速度就越快。 文档应该具有统一的外观，并包括所有相关信息：端点，兼容方法（GET，POST，PUT等），哪些参数是可选的和必需的以及预期的数据类型。

这个来自Heroku平台API文档的屏幕截图展示了开发人员所需的完整文档。 它显示了已执行的操作，访问的端点以及使用的HTTP方法。 它还提供了有关可选参数的详细信息，并向用户显示了正确实施的所有示例的工作示例。 样本响应还说明了如何构造返回的数据。

Heroku的API文档干净，井井有条，可为开发人员提供所需的一切。

3.速率限制和节流

API请求可能会占用大量资源，需要大量的计算能力和存储空间。如果您不小心，大量连续的并发请求可能会减慢服务器速度甚至使您的DOS慢下来，一种简单的方法是使用许多可用工具之一，例如express-rate-limit（一种设计为Express的中间件）专门用于以简单，直观的方式处理限速。您还可以实现与身份验证绑定的速率限制逻辑，从而在控制授予每个用户的权限方面具有更大的灵活性。通过要求用户进行身份验证，可以跟踪每个用户发送的请求数量，这也使您可以限制或停止这些请求。还可以授予不同的用户访问不同的API端点的权限。例如，与普通非特权用户相比，管理员用户可以通过API访问更多信息或更多请求。使用身份验证的另一个好处是它提供的安全性，使我们进入了下一个最佳实践。

4.保护API

API必须安全！%20黑客使用自动脚本随意攻击服务，因此API需要采取主动安全措施，以保持操作顺畅运行并保护敏感数据。%20首先，每个Web应用程序都应具有HTTP严格传输安全性（HSTS）策略，以确保所有连接均被加密。%20确保连接的安全性可以防止网络嗅探，中间人攻击，协议降级攻击以及通过cookie盗窃进行会话劫持。%20您可能还希望设置和隐藏某些可以利用的标头，例如那些揭示有关您的API基础结构的信息的标头，这些信息可能对攻击者有用。%20有很多工具可以解决这个问题。%20例如，如果您使用Node.js运行API，则可以使用Helmet.js之类的东西。%20实现此中间件很容易：

为防止API泄漏敏感的客户数据（例如密码），请编写单元测试以进行安全性测试。 最后但并非最不重要的一点是，您应该要求身份验证令牌才能访问您的API。 这使开发人员可以控制谁有权访问哪些信息。 通过拒绝冒犯用户，它还可以使阻止API服务器上的攻击变得更加容易。

5.使用JSON

API的目的是从公司资源中提供数据。 根据北欧API，通常使用三种格式来返回数据：XML，YAML和JSON。

XML易于人类阅读，但是数据包含在一组标记标签中，这些标记迅速增长并且需要额外的带宽。 开发人员还必须解析标签的内容才能访问数据。相比之下，YAML仅占用很少的带宽，但需要使用外部库或自定义的解析器和编码器来处理数据.JSON与XML完美地融合在一起 和YAML一起使用：它是人类可读的，不需要高带宽或自定义解析即可将数据移入JAVAScript兼容结构。

结论

使用RESTful API实现这五种做法将使您的API更加易于使用和安全。 具有良好文档的安全，可靠的API可以提供出色的开发人员体验，并且更高的易用性将帮助您提高采用率。 此外，这些最佳实践将使您的代码保持整洁，操作平稳进行，并使客户满意。

(本文翻译自Michael Bogan的文章《5 Best Practices for Designing RESTful APIs》，参考：
https://medium.com/swlh/5-best-practices-for-designing-restful-apis-42f55cb787d3)