提高 Web API 的 5 个小步骤

原文：https://medium.com/hackernoon/5-small-steps-to-a-better-web-api-6fa9698178a6

Random picture of a Mac, because that’s how work gets done

作为一名网络开发人员，我最喜欢做的事情之一就是设计和构建单页应用程序。这意味着我相当定期地与 WebAPI密切合作。我甚至自己设计了 Web APIs，并取得了不同程度的成功。

以“API 优先”模式构建你的应用程序有很多优势，而且它肯定会变得越来越流行，所以在你开始下一个大的构建之前，我想分享一些你可以做的小事情，它们将极大地改进你的 API 的设计。

在我们开始之前，我想提一下这些事情仍然很重要，即使你的 API 是私有的。随着应用程序的开发，私有 API 会逐渐公开，除此之外，一个好的 API 会加速前端客户端的开发，无论是 spa、移动应用还是脚本。

使用正确的状态代码！

HTTP 标准包括一个非常全面的状态代码数组，供服务器作为主体的元数据返回。这些代码可以为 API 的消费者提供一种很好的方式来以编程方式弄清楚发生了什么，而不必求助于解析脆弱的错误消息。

状态代码分为以下几类:

1xx 信息(主要用于服务器)
2xx 成功！
3xx 重定向
4xx 客户端错误(呼叫者可以修复的问题)
5xx 服务器错误(呼叫者无法解决的问题)

我相信我们都熟悉 404 未找到，但 409 冲突呢？返回这些更具体的代码有助于客户端以更合适的方式处理错误(或不同类型的成功)。

哦看在上帝的份上，不要为了每件事都回 200 成功，靠身体里的一个信息来解释发生了什么。很讨厌。这就引出了我的下一个观点…

不要在正文中包含元数据

当您的 API 返回对请求的响应时，它将在响应正文中发送大部分数据。这就是身体的目的。但是如果客户机请求数据的分页视图呢？您需要通知客户端各种元数据，比如集合中的项目总数。那通向哪里？

这个问题的一个常见解决方案是返回用某种包装器包装的数据，如下所示:

{
  total: 100,
  page: 2,
  results: [ ... ]
}

我不喜欢这样，因为它模糊了资源和接收资源的方法之间的界限。那么元数据应该放在哪里呢？在标题中。

HTTP 标准允许将自定义头与响应一起发送。最初，人们建议自定义头以 X 为前缀，如 X-Forwarded-By。由于很难将以前的非标准标题集成到标准中，该建议被撤回。X 前缀的另一种替代方法，最初是为了避免冲突，是用您的应用程序名命名您的头。例如:

BobsBurgers-ItemCount: 200

支持多个快速请求，而不是单一请求

当我们从 API 而不是传统的回发模型中使用数据时，我们可以在数据加载时完全控制 UI，因此我们能够以一种渐进的方式向用户显示数据，并且在数据可用时立即显示。因此，你应该倾向于设计多个快速返回的端点，而不是每页一个端点。总的加载时间可能会更长，但如果我的用户在我给她看电影大纲的几秒钟内看不到复杂的电影评分计算，也没关系。它还允许客户端根据用户的操作来区分请求的优先级。如果我的用户没有向下滚动那么远，我可能根本不需要加载那个评级。

生成文档

大多数 web 框架都有轻松生成详细 API 文档的最佳实践。作为构建过程的一部分，使用它并保持更新。它不需要很多手写的描述，但是它需要一个参数列表和一个请求和响应的例子。像这样简单的事情可以在 API 开发和客户端开发之间来回切换，节省几个小时的开发时间。依靠文档中规定的合同，而不是依靠一千条松散的消息。

保持一致

从理论上讲，我应该能够准确地猜出我想要访问的资源的 URL 或者我想要执行的操作，只要给出几个例子。只要保持一致性和可预测性，采用什么样的 URL 方案并不重要(例如，REST 标准没有做出任何规定)。最小惊讶原则适用于此。

如果你喜欢这篇文章，请记得给它一些掌声，以确保更多的人阅读它！

Steven Poulton 是一名居住在英国曼彻斯特的网站开发人员和技术架构师。在业余时间，他喜欢制作独立音乐，制作独立游戏，和他的独立猫玩耍。