REST API开发技巧和最佳实践（三）

文件资料

与任何类型的软件项目一样，好的文档对提高API的采用速度有很大帮助。

本系列第一篇文章的“规范”部分中最流行的两个选项也可以作为文档选项来解决。 如果您采用了OAS，那么您已经有了一个出色的解决方案，可以以Swagger UI的形式对API进行文档编制和集成手动测试。

Postman应用程序在这方面提供了类似的功能，并且作为最后的选择，您始终可以选择从头开始创建自己的文档（尽管这将更难以维护，并且将缺少集成的测试环境）。

1.不要忘记错误

尽管您的使用者通常可以通过缺乏信息和少量测试请求来轻松确定API的资源和架构，但API返回的错误却很难发现。 您需要详细记录所有这些文件，并结合可以返回它们的端点和/或导致它们发生的条件

经验表明，错误是文档中团队无法更新以反映其代码更改的第一件事（当工作中未使用规范的方法（例如OAS或类似方法）时）。

2.实体参考

如果您的应用程序足够大，则您的API可能会返回多种类型的实体，有时它们之间可能具有复杂的关系。 这些实体中的某些实体可能会变得足够大，以包含您可能不想在每次调用中返回的大量数据。

字段过滤可能会返回对象的默认过滤视图，该视图仅列出了少数几个可用属性，因此无法通过简单的请求向用户提供每个实体的完整概述。

在这种情况下，最好有一个完整的可用实体的单独索引，供开发人员浏览以消除每个字段的使用和实体之间的关系的歧义。 此外，如果您不提供SDK或一组业务对象，那么它们是极好的资源，他们可以用来在客户端上开发自己的数据模型。

3.版本历史

这一点对于确保您的客户端始终保持最新非常重要。 您可以向API添加不间断的增量更新，而不必弃用您的主要版本（使次要版本增加），但是您应将这些清楚地告知使用者。

您应该为仍可在生产环境中使用的每个API新版本（甚至次要版本）维护一个单独的文档版本。 这样，即使他们跳过了一些次要版本，您的用户也可以尽快跟踪您的更改，并在下一个客户端应用程序版本中利用它们。

版本之间的可用更改日志也非常有用，可以快速概述所有更新。

超越常规

正如我在简介中所提到的，这篇文章尽其所能，不会重复您在其他所有REST API开发资源中在线阅读的常见建议。 基于此，我假设您在到达这里之前已经阅读了至少两个类似这样的资源，并且对API需要实现的基本功能有清楚的了解。

在本部分中，我将提及一些多年来不太有用的功能，这些功能我多年来发现非常有用，并且不会经常提及。

1. HATEOAS

尽管Roy Fielding的论文论文指出，没有HATEOAS就没有REST，而且人们甚至呼吁不支持RESTless的API，但是越来越多的人发现HATEOAS…有问题（轻描淡写）。

直到几年前，我对REST API设计采取了严格的实用方法。由于不得不从事具有悠久历史和严重版本控制问题的大型项目，我不得不重新评估自己的方法。虽然我仍然对HAL膨胀或其他Hypermedia格式是否合理表示怀疑，但我确实赞赏诸如GitHub使用Hypermedia之类的实用解决方案（尽管GitHub已针对其API的最新版本移至GraphQL）。

我不会声称自己对HATEOAS以及它所吹捧的所有优点在实践中对API都有完全的了解，但是我已经对其中的一些内容表示赞赏。我还没有看到理想的客户端-仅通过了解API的基本URL就能工作的客户端，但这也有可能是因为我没有进行足够的搜索。

2.缓存

HTTP协议从早期网络时代开始就支持缓存机制，并取得了不同程度的成功。尽管可以改进初始协议标准，但故障通常归因于服务器配置错误或服务器或客户端（包括早期的Web浏览器）实施不充分。

我们即将到2018年底，HTTP 1.1几乎可以普遍使用，随着HTTP 2.0的采用迅速增加，但是许多Web API（不是主要公司的API）一直完全忽略标准协议缓存机制。充其量，客户端将尝试使用自己的缓存方法（通过API响应中提供的隐含参数），而在最坏的情况下，将根本没有缓存。

上面的情况听起来很糟糕，但考虑到整个协议缓存基础结构对于大多数客户端（浏览器，本机网络库等）自动运行，只要API返回正确的缓存头，情况就更糟了！如果听起来还不那么麻烦，请通过在API中使用缓存来帮助改善网络。

由于您可以在线阅读许多资源，因此我将不会讲HTTP缓存机制的所有详细信息，但是如果您知道缓存的一般含义，那么在这种情况下实现缓存要比您想象的容易得多。您要做的就是让客户端知道是否允许他们缓存响应以及何时您希望其内容发生更改（从而使缓存无效）。

如果您希望客户端缓存特定的响应，但是不确定何时更改，则不要让客户端每次都下载整个响应正文。只需使用ETag，您只需提供一个简短的答复即可告知他们，自他们上次下载以来，他们所请求的内容是否已更改。最后，除非必须支持真正的旧客户端，否则，您可以完全跳过HTTP 1.0缓存机制（尽管如果您做的其他一切都正确，则实现起来很简单）。

3.速率限制

通常，速率限制是API开发人员实施的最后一件事，通常是在报告了某种服务滥用之后。我相信它应该是服务于少数用户的任何API的组成部分，并且应谨慎实施。

开发人员常犯的一个错误是依赖于仅在开发过程中由几个人测试过的幼稚的实现。不要傻了！一个简单的算法可以测量IP地址与时间的关系，这很可能会给您的B2B造成大量的拒绝服务，他们的网络客户端使用的IP空间有限！请始终考虑身份验证令牌，并要非常小心如何实施速率限制-否则，在您自学并考虑所有可能的后果之前，请不要这样做。

如果您的API确实实施了速率限制，请确保通过响应标头提供其当前状态来通知您的用户。如果您需要灵感，请查看Twitter和GitHub上的一些示例。

4.Accept-Language标头

尽管这个非常重要且无处不在的请求标头非常有用，但却经常被人们忽略。 它的基本作用是提供客户端支持的服务器语言列表（按优先顺序）。

我见过许多API使用自定义参数进行语言选择并忽略了此标头，尽管大多数客户端默认情况下都会发送标头（尊重最终用户的本地化首选项）。 当您的API需要提供任何类型的本地化内容时，可以使用此方法。

结束

感谢您阅读本文。 希望您不会觉得阅读这一系列的帖子过于费劲，并且它们至少为您提供了少量的相关信息，以帮助您构建出色的API。