全栈开发必备技能：构建RESTful API的13种最佳实践

首发于公众号《前端全栈开发者》，第一时间阅读最新文章，会优先两天发表新文章。

Facebook、GitHub、Google以及其余许多巨头都须要一种服务和消费数据的方式。在当今的开发环境中，RESTful API仍然是服务和消费数据的最佳选择之一。

可是你是否考虑过学习行业标准？设计RESTful API的最佳实践是什么？从理论上讲，任何人均可以在不到五分钟的时间内快速启动数据API——不管是Node.js，Golang仍是Python。

咱们将探讨在构建RESTful API时应考虑的13种最佳实践。但首先，让咱们快速阐明RESTful API。

什么是RESTful API？

RESTful API须要知足如下约束才能被称为RESTful API。

1. 客户端-服务器模型：RESTful API遵循客户端-服务器模型，其中服务器为数据提供服务，而客户端链接到服务器以使用数据。客户端和服务器之间的交互是经过HTTP（S）请求进行的，该请求传输了请求的数据。
2. 无状态：更重要的是，RESTful API应该是无状态的。每一个请求都被视为独立请求。服务器不该跟踪可能影响未来请求结果的任何内部状态。

3. 统一接口：最后，一致性定义了客户端和服务器之间的交互方式。RESTful API定义了命名资源的最佳实践，但定义了容许你修改资源/与之交互的固定HTTP操做。能够在RESTful API中访问如下HTTP操做：

   • GET请求：检索资源
   • POST请求：建立资源或将信息发送到API
   • PUT请求：建立或替换资源
   • PATCH请求：更新现有资源
   • DELETE请求：删除资源

在对RESTful API的特性有了更深刻的了解后，是时候了解更多关于RESTful API的最佳实践了。

本文为你提供了13种最佳实践的可行清单。让咱们来探索！

1.正确使用HTTP方法

咱们已经讨论了可用于修改资源的HTTP方法：GET，POST，PUT，PATCH和DELETE。

尽管如此，许多开发人员仍是倾向于滥用GET和POST或PUT和PATCH。一般，咱们看到开发人员使用POST请求来检索数据。此外，咱们看到开发人员使用PUT请求来替换资源，而他们只想更新该资源的单个字段。

确保使用正确的HTTP方法，由于这将为使用你的RESTful API的开发人员增长不少混乱。最好是坚持使用预约的准则。

2.命名约定

了解RESTful API命名约定将对你有组织地设计API有很大帮助。根据你服务的资源设计一个RESTful API。

例如，你的API管理着做者和书籍（是的，一个经典的例子）。如今，咱们要添加一个新做者或访问一个ID为 3 的做者。你能够设计下面的路由来达到这个目的：

• api.com/addNewAuthor
• api.com/getAuthorByID/3

想象一下，一个API承载了许多资源，每一个资源都有许多属性。可能的端点列表将变得无穷无尽，并且对用户不是很友好。因此咱们须要一种更有条理和标准化的方式来设计API端点。

RESTful API最佳实践描述了端点应以资源名称开头，而HTTP操做则描述操做。如今咱们获得：

• POST api.com/authors
• GET api.com/authors/3

若是咱们想访问ID为 3 的做者曾经写过的全部书籍怎么办？对于这种状况，RESTful API也有解决办法：

• GET api.com/authors/3/books

最后，若是您要为ID为 3 的做者删除ID为 5 的书，该怎么办？一样，让咱们遵循相同的结构化方法来造成如下端点：

• DELETE api.com/authors/3/books/5

简而言之，利用HTTP操做和资源映射的结构化方式来造成易于理解的端点路径。这种方法的最大优势是，每一个开发人员都了解RESTful API的设计方式，他们能够当即使用API，而没必要阅读你的每一个端点的文档。

3.使用复数资源

资源应始终使用其复数形式。为何？假设你要检索全部做者。所以，你将调用如下端点：GET api.com/authors。

当你读取请求时，你没法判断API响应是否只包含一个或全部做者。所以，API端点应该使用复数资源。

4.正确使用状态码

状态码在这里不仅是为了好玩，它们有一个明确的目的，状态码通知客户端请求的成功。

最多见的状态码类别包括：

• 200（OK）：请求已成功处理并完成。
• 201（Created）：指示成功建立资源。
• 400（Bad Request）：表明客户端错误。也就是说，请求的格式不正确或缺乏请求参数。
• 401（Unauthorized）：未受权，你尝试访问你没有权限的资源。
• 404（Not Found）：请求的资源不存在。
• 500（Internal Server Error）：内部服务器错误，服务器在执行请求期间引起异常。

状态码的完整列表能够在Mozilla Developers找到。

5.遵循相同约定

最多见的是，RESTful API提供JSON数据，所以，应遵循camelCase大小写惯例。可是，不一样的编程语言使用不一样的命名约定。

6.如何处理搜索，分页，过滤和排序

搜索，分页，过滤和排序等操做并不表明单独的端点。这些操做能够经过使用随API请求提供的查询参数来完成。

例如，让咱们检索按名称升序排列的全部做者。你的API请求应以下所示：api.com/authors?sort=name_asc。

此外，我想检索一个名称为“ Michiel”的做者。该请求看起来像这样 api.com/authors?search=Michiel。

幸运的是，许多API项目都带有内置的搜索、分页、过滤和排序功能。这将为你节省不少时间。

7.API版本控制

我不常看到这一点，但这是对你的API进行版本调整的最佳实践。这是一种有效的方式来向你的用户传达重大的变化。

一般，API的版本号包含在API URL中，例如：api.com/v1/authors/3/books。

8.经过HTTP标头发送元数据

HTTP标头容许客户端随其请求发送其余信息。例如，Authorization 标头一般用于发送身份验证数据以访问API。

你能够在此处找到全部可能的HTTP标头的完整列表。

9.限速

速率限制是控制每一个客户端请求数量的一种有趣方法。这些是服务器可能返回的速率限制标头：

• X-Rate-Limit-Limit：告诉客户端在指定时间间隔内能够发送的请求数。
• X-Rate-Limit-Remaining：告诉客户端在当前时间间隔内仍能够发送多少个请求。
• X-Rate-Limit-Reset：告诉客户端速率限制什么时候重置。

10.有意义的错误处理

若是出现问题，请务必向开发人员提供有意义的错误消息，这一点很重要。例如，Twilio API返回如下错误格式：

{
  "status": 400,
  "message": "Resource books does not exist",
  "code": 24801,
  "more_info": "api.com/docs/errors/24801"
}

在此示例中，服务器返回状态代码和人类可读的消息。此外，还返回内部错误代码，供开发人员查找特定错误，这使开发人员能够快速查找有关该错误的更多信息。

11.选择正确的API框架

存在许多用于不一样编程语言的框架，选择一个支持RESTful API最佳作法的框架很是重要。

对于Node.js，后端开发人员喜欢使用Express.js和Koa，而对于Python，Falcon是一个不错的选择。

12.文档化你的API

最后，写文档！我不是在开玩笑，这仍然是传递你新开发的API知识最简单的方法之一。

尽管你的API遵循RESTful API列出的全部最佳实践，但仍然值得你花时间记录各类元素，好比API处理的资源或应用于服务器的速率限制。

想一想你的其余开发人员，文档大大减小了学习API所需的时间。

13.把事情简单化！

不要让你的API过于复杂，保持资源简单。正肯定义你的API处理的不一样资源，将帮助你在将来避免资源相关的问题。定义你的资源，还要准肯定义它的属性和资源之间的关系。这样一来，如何链接不一样的资源就没有争议的空间了。

若是您喜欢这篇介绍API最佳实践的文章，那么您可能还喜欢从头开始学习构建RESTful API。