为不同的使用者设计REST

Question

我有一个在两个场景中使用的应用程序API：

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

开始时，所有端点都是泛型的，因此在这两种场景中都使用过它们，但是随着应用程序的增长，我需要：

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

设计API以满足这些需求的最佳实践是什么？如何才能正确地设计，以便根据前端的需要进行调整，另一方面，它将足够健壮，不会破坏客户端的应用程序？前端特定端点与通用端点一起？

Answer 1

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

这在很大程度上取决于您的场景。您的API将仅在内部使用，还是会向未知数量的开发人员和集成商公开使用？API的预期寿命是多少？它会进化吗？

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

我建议提交API契约，并为这些契约使用规范。我更喜欢OpenAPI规范，因为它会带来很多好处。确保您花费了大量的时间和团队努力(产品负责人、项目经理、后端和前端开发人员)在几次迭代中开发合同。每次迭代之后，通过模拟API和客户端来测试规范，然后再转到实现前端应用程序或cli客户端。

前端特定端点与通用端点一起？

我不会那样做，但我不知道你的背景。前端特定端点意味着什么？如果这意味着，从今天起，端点只应该由前端应用程序使用，但是对于当前的cli客户端没有任何用处，我认为这只是一个透视图问题。让它成为一个通用端点，并通过前端应用程序使用它。如果它提供了一些只应由前端访问的敏感信息，则需要考虑身份验证和授权。为此，我建议实现Oauth2。

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

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

你写了你需要：

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

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

如果您需要改变现有的行为，您应该考虑API版本化或API演化，这是一个以许多不同的观点和实践来讨论争论的话题。

Answer 2

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

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

如果您深入研究旧有的XML文献，您会发现对诸如Must Ignore和Must Forward这样的想法的引用--这些原则也适用于长寿资源的表示。

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