REST API开发技巧和最佳实践-第3部分

这是有关REST API的三篇文章系列中的最后一篇。

第1部分:简介和计划
第2部分:架构建议,常见错误和不建议使用
第3部分:文档提示和超越基础知识

文件资料

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

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

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

1.不要忘记错误

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

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

2.实体参考

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

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

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

3.版本历史

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

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

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