REST API URI设计模式：非分层路径？

Question

在工作中，我们正在讨论如何构建即将到来的API。到目前为止，我们将启动一个包含不同用户信息端点的API，尽管我们将其发布在如下api.mycompany.com/userinfo这样的URI下。端点示例：

• api.mycompany.com/userinfo/users
• api.mycompany.com/userinfo/users/ {id}
• api.mycompany.com/userinfo/api-docs <-此特定API的Swagger文档将位于此处

这种类型的设置将允许我们让server1.mycompany.com托管API，并使用我们的负载平衡器/代理将流量转发到api.mycompany.com/userinfo到server1.mycompany.com。对于在server2.mycompany.com上运行的下一个API，我们将使负载均衡器/代理将流量从api.company.com/transportation转发到server2.mycompany.com，如下所示：

• api.mycompany.com/transportation/cars
• api.mycompany.com/transportation/cars/ {id}
• api.mycompany.com/transportation/api-docs <-此特定API的Swagger文档将位于此处

通过在URI中使用“ userinfo”和“ transportation”，我们将有一种简单的方法来整体引用我们不同的API，并有一种在实际API旁边发布Swagger UI的简单方法。

我对这些URI的担心是它们不是分层的，而是更像是将端点组合在一起的一种方式。 “ userinfo”也不是一种资源，因此，与通常在网上遇到的REST API示例相比，在路径中使用“ userinfo”和“ transportation”之类的元素可能并不是最佳做法。

此设计是否破坏了任何REST API设计模式？如果是这样，您如何建议我们在单个fqdn（api.mycompany.com）下发布不同的API？还是有理由不对我们所有的API使用单个fqdn？

任何输入将不胜感激。

Answer 1

REST不在乎您的URI使用什么拼写

  

我对这些URI的担心是它们不是分层的，而是更像是将端点组合在一起的一种方式。 “ userinfo”也不是资源

标识符是“分层的”并不能（必然）承诺关于资源的层次结构。存在List<OutputStream?>标识的资源的事实不是，这并不意味着也存在/userinfo/users标识的资源。考虑密钥/值存储，而不是文件系统。

Rails开发人员可能将/userinfo和/userinfo识别为namespaces。

  

如果是这样，您如何建议我们在单个fqdn（api.mycompany.com）下发布不同的API？还是有理由不对我们所有的API使用单个fqdn？

在2014 interview中，菲尔丁提供了有关版本控制的答案：

  

总是有可能出于某些不可预料的原因而需要一个完全不同的API，尤其是在接口的语义更改或安全性问题要求放弃以前部署的软件时。我的观点是，无需使用版本ID就能预见到如此世界性的更改。我们有该主机名。您创建的不是API的新版本，而是具有新品牌的新系统。

如果您这样斜视，则可能意味着不同的（逻辑）主机上应该有不同的API。

Answer 2

  

此设计是否破坏了任何REST API设计模式？

不。没有“ REST API设计模式”。 REST并没有说明URL的外观。 REST表示将它们视为不透明。有一种观点认为，Web API URL应该是“可入侵的”，也就是说，人类很容易理解和修改。我认为您的URL结构是可入侵的。我不知道任何有说服力的论点，即URL本质上必须是分层的。