Rest API 命名约定是不是过于冗长？

Posted 2023-03-08

【中文标题】Rest API 命名约定是不是过于冗长？

【英文标题】：Is Rest API naming convention too verbose?Rest API 命名约定是否过于冗长？

【发布时间】：2018-02-04 01:27:41

【问题描述】：

我正在设计我公司正在构建的一个研发应用程序的 API 层。 API 的目的是共享数据库中的数据并为我们的数据提供计算功能。

我的想法是构建遵循经典模式资源名词和休息动词的控制器端点：

GET /api/v1/organisations
GET /api/v1/organisations/id
GET /api/v1/organisations/id/offices

等等

将项目交给我的开发人员强烈建议我不要使用这个约定，他说公司正在远离这个约定，因为它太冗长，因此效率不高。

他建议采用结构较少的端点。像这样，来自代码：

GET /api/v1/taxEnvId/covers 
GET /api/v1/coverId/occupclasses

例如，第一个 url 可以是任何东西。

我反对说它不应该在效率方面发生太大变化，并且我建议的设计在自我文档方面的优势将大于（在我看来）非常小的低效率（在每个请求发送的字节数）由更长的路径引入。

他比我更有经验，所以我想知道我在当前的“设计”中是否犯了错误。

经典的动词 - 名词休息名称约定是错误的吗？ 使用该约定有什么我看不到的缺点吗？ 他是否强调该公约效率低下？

我在互联网上找不到任何人抱怨该约定，我很乐意听取其他意见，甚至重定向到书籍和链接，以使我对这部分设计的评估更好。

【问题讨论】：

我看不出他的设计有什么好处。为什么 ID 会在该 ID 所代表的描述之前？这对我来说完全不直观。他能描述一下这种设计的“效率”收益吗？因为我不是通过 URL 单独看到它们的。

不要破坏你的想法，但我听说 GraphQL 是下一个 REST

无论如何，关于建议的选项。我认为/covers?id=taxEnvId 会“更有效率”

这个问题真的是针对 REST 还是只是针对任何 HTTP API 的流行语？在初级情况下，URL 的结构根本不重要，重要的是您为 URI 提供的关系名称，这是 RESTful 客户端用来决定是否调用它的名称。此外，如果最小化数据负载是最高优先级，则 REST 可能是错误的架构，因为您必须在响应中添加的所有元数据和链接以及对每个 URI 的来回协商和选项检查都可以弥补一般会增加一些额外的开销。

【参考方案1】：

恕我直言，您的方法似乎更清晰，更易于理解。 API 必须直观且易于使用。

一些可能对您有用的链接：

RESTful Resource Naming Introduction to REST Endpoints Best Practices for Designing a Pragmatic RESTful API Twitter REST API Reference Documentation

【参考方案2】：

我反对说它在效率方面不应该有太大变化

既然变化并没有那么不同，那么值得争论吗？如果他是高级工程师，而组织想尝试更小的路径方法，那么这是帮助组织实现这一目标的机会。如果最终他们对不那么冗长的 URL 路径的更改导致没有任何改进，您可以放心，您帮助得出了这个结论。你必须选择你的战斗并且两个 URL 看起来非常相似，如果最终归结为意见，那么真的不值得争论，特别是当团队已经表示有兴趣使 URL 路径不那么冗长时。

【参考方案3】：

如果您（公司）不仅在 API 中提供数据，还提供功能，那么 Rest 是一个不错的选择。否则 GraphQL 可能是一回事，两者基本上都是different。 简而言之：如果您不提供业务逻辑，GraphQL 就会大放异彩。

我对你的方法的争论是/v1，因为那不是资源。版本控制本身就是一个主题。

我觉得采用这个不是很有效：

GET /api/v1/taxEnvId/covers 
GET /api/v1/coverId/occupclasses

想象一下后备控制器。 API 的类型越多，这个控制器就会越混乱。如果发生这种情况，这怎么可能更有效或更高效？ 网址很短，但网址很便宜。 如果他争论要发送的字节数，请向他介绍 gzip 压缩。