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

Question

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

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

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可以是任何内容。

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

经典的动词-名词rest命名约定是错误的吗？使用该约定有什么我看不到的缺点吗？他强调这种惯例是无效的，这是对的吗？

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

Answer 1

我觉得你的方法看起来更清晰，更容易理解。API必须直观且易于使用。

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

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

Answer 2

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

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

Answer 3

如果您(该公司)在您的API中不仅提供数据，还提供功能，那么Rest是一个很好的选择。否则，GraphQL可能是一种东西，两者从根本上都是different。简而言之:如果你不提供业务逻辑，GraphQL就会大放异彩。

我认为你的方法是/v1，因为它不是一种资源。版本化本身就是一个主题。

我发现采用这样的方法效率不高：

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

想象一下后备控制器。API的类型越多，这个控制器就会变得越混乱。如果发生这种情况，这怎么可能更有效率呢？urls很短，但是urls很便宜。如果他对发送的字节有争议，就向他介绍gzip压缩。