为不同的消费者设计REST API

Question

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

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

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

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

设计满足这些需求的API的最佳实践是什么？ 应该如何正确设计才能进行调整 满足前端需求，并且另一方面是否足够健壮而不会破坏客户端的应用程序？ 前端特定端点以及常规端点？

Answer 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。

Answer 2

  

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

设计资源表示，以使它们在设计上前后兼容。从根本上说，它们是消息，因此请按这种方式对待它们。可以将具有合理默认值的新的可选字段添加到消息中，但消息元素的语义永远不应更改。

如果您翻阅旧的XML文献，您会发现对诸如Must Ignore和Must Forward之类的想法的引用-这些都是原则，也适用于寿命长的资源的表示形式。

在无法方便地扩展现有资源来覆盖您的新用例时，创建新资源。