REST API - 如何构建端点 url

Posted 2023-02-19

【中文标题】REST API - 如何构建端点 url

【英文标题】：REST API - How to structure endpoint urls

【发布时间】：2021-08-08 23:44:18

【问题描述】：

我正在创建一个 REST API，但我对如何组织以下端点的 url 有一些疑问：

列出所有大学 列出给定大学的所有学院 检索学院/大学的详细信息

我认为有这样的东西是有意义的（虽然最后一个有一个不必要的参数，inst_id，为了便于阅读，我决定在那里）：

#list all universities
/api​/v1​/universities     

#retrieve university detail
/api/v1/universities/inst_id

#list faculties of a university
/api/v1/universities/inst_id/faculties     

#retrieve details of a faculty
/api/v1/universities/inst_id/faculties/inst_unit_id  

这样做的问题是，大学和教师的详细信息是由同一个服务提供的，所以有两个网址没有意义。

那我应该如何组织呢？我认为这两个选项都可以：

使用大学 URL 检索教师详细信息。这很好，因为没有不必要的参数，但在列出所有学院后，它有点“返回”以获取学院详细信息：

    #list all universities
    /api​/v1​/universities     
    
    #retrieve university/faculty detail
    /api/v1/universities/inst_id
    
    #list faculties of a university
    /api/v1/universities/inst_id/faculties

使用教师 URL 检索大学详细信息。我认为这样的流程更容易理解，它不会在路线中“返回”。但是，最后一个端点接收到一个不必要的参数，并且大学详细信息 url 不是紧跟在路由中的大学 url 列表之后：

    #list all universities
    /api​/v1​/universities     
    
    #list faculties of a university
    /api/v1/universities/inst_id/faculties

    #retrieve university/faculty detail
    /api/v1/universities/inst_id/faculties/inst_unit_id 

我应该使用哪一个？还有其他建议吗？

谢谢！

【参考方案1】：

没有 REST 端点这样的东西。 -- Fielding, 2018

REST 有resources。 REST 资源的一个常见示例是网页；例如，您正在阅读的那本。

您在这里面临的设计问题类似于“大学”网页是否应包含教师列表的问题。无论哪种方式都很好。

如果您使用的媒体类型的处理规则了解 fragments（例如 html），那么您可以提供教师列表的标识符作为辅助资源：

/api/v1/universities/inst_id#faculty

在一个或两个网页之间进行选择可能需要考虑不同的权衡。例如，如果网页的“大学”部分比“学院”部分大得多，并且变化比“学院”部分慢，那么您可以考虑将它们分开，以便您可以分配不同的caching meta两个部分的数据。