为不同的消费者设计 REST API答案

【问题标题】：Designing REST API for Different Consumers为不同的消费者设计 REST API
【发布时间】：2019-12-12 12:33:59
【问题描述】：

我有一个在两种情况下使用的应用程序 API：

我的前端应用程序使用它与服务器交互
客户正在使用它来开发 CLI 工具，因此有一个开放的 API 文档。

一开始，所有端点都是通用的，因此它们已在两种情况下都使用过，但随着我的应用程序的增长，我需要：

为我的前端应用程序创建特殊端点以进行优化，例如某个统计屏幕的端点
更改一些不向后兼容并可能破坏客户端的基本 API 结果结构用法。

设计 API 以满足这些需求的最佳做法是什么？应该如何正确设计以便对其进行调整满足前端需求，另一方面将足够强大而不会破坏客户端的应用程序？前端特定端点以及通用端点？

【问题讨论】：

1.有时您需要专门的端点。这并不理想，但无论如何，它发生在现实世界中。 2. API 版本控制解决了向后兼容性问题。您应该告诉客户，尽管他们需要在一段时间内更新到新版本

标签： rest api-design

【解决方案1】：

设计 API 以满足这些需求的最佳做法是什么？

这在很大程度上取决于您的情况。您的 API 将仅在内部使用，还是将公开提供给未知数量的开发人员和集成商？ API 的预期生命周期是多少？会进化吗？

应该如何正确设计，以便根据前端需求进行调整，另一方面又足够健壮，不会破坏客户的应用程序？

我建议承诺 API 合同并为这些合同使用规范。我更喜欢OpenAPI specification，因为它会带来很多好处。确保您投入大量时间和团队努力（产品负责人、项目经理、后端和前端开发人员）在多次迭代中开发合同。在每次迭代之后，通过模拟 API 和客户端来测试规范，然后再转而实施您的前端应用程序或 cli 客户端。

前端特定端点以及通用端点？

我不会那样做，但我不知道你的上下文。前端特定端点是什么意思？如果这意味着截至今天，端点应该只由前端应用程序使用，但对当前的 cli 客户端没有用，那么我认为这只是一个观点问题。使其成为通用端点，并由前端应用程序使用。如果它在某种程度上提供了只能由前端访问的敏感信息，您需要考虑身份验证和授权。我建议为此实施Oauth2。

为我的前端应用程序创建特殊端点以进行优化，例如一些统计屏幕前端特定端点以及通用端点的端点？

我建议在您的 API 中实现所有端点并使用 OAuth2 作为身份验证。使用 OAuth 方法的范围来管理每个客户端（前端应用程序、cli）对不同端点的授权和访问。

你写道你需要：

更改一些不向后兼容且可能破坏客户端使用的基本 API 结果结构。

尽量避免对您的 API 进行重大更改。如果它仅在内部使用，您可以控制访问 API 的不同客户端，但即使破坏客户端的风险也很高。

如果您需要改变现有行为，您应该考虑API versioning 或API evolution，即controversly discussed topic with a lot of different opinions and practices。

【讨论】：

感谢您的详细回答。当我写前端“特定”端点时，我的意思是我的仪表板屏幕之一必须按不同类别显示大量汇总数据。当我使用常规端点时，我的性能非常糟糕，因为我必须为该屏幕创建一些性能优化的端点，正如您所了解的，它将仅在此屏幕中使用（非常具体）。以这种方式 - 为特定消费者创建端点

【解决方案2】：

设计 API 以满足这些需求的最佳做法是什么？

设计您的资源表示，以便它们在设计上向前和向后兼容。从根本上说，它们是消息，所以要这样对待它们；可以将具有合理默认值的新可选字段添加到消息中，但消息元素的语义永远不会改变。

如果您翻阅旧的 XML 文献，您会发现对 Must Ignore 和 Must Forward 等想法的引用——这些原则也适用于长期资源的表示。

当现有资源无法方便地扩展以涵盖您的新用例时，请创建新资源。

【讨论】：