RESTful API 的根资源应该有什么？

Question

向 API 请求“/cats”会返回猫的集合，而请求“/cats/123”会返回 id 为“123”的猫

我的问题是：当请求'/'（API的根）时应该响应什么？

也许是包含 API 中所有集合名称的索引？

Answer 1

这个问题可能没有客观的答案，但一个很酷的 API 应该是可浏览的。这意味着，给定一个起始 URI，应该可以“发现”完整的 API，因此拥有一个链接到 API 的所有不同部分的根资源肯定会有所帮助。

即使所有服务都是单独的应用程序（想想微服务），我仍然会创建一个服务来为所有服务提供“开始”链接，从而真正为整个应用程序提供一个入口点。

我的意思是，不仅供人类浏览，而且客户端也会从第一个 URI 开始。总是，除非使用以前状态的书签（并且在给定重定向或未找到时需要维护这些书签）。

Answer 2

我不知道这是否有一个固定的约定。这取决于您想要提供什么以及您的安全顾虑是什么。您可以考虑在 REST API 中返回有效对象的列表。或者，如果您不想向任何人透露该信息，请考虑返回 204 或 404。

Answer 3

尽管这个讨论已经消亡多年，但考虑到在谷歌搜索该主题时它仍然显示为热门搜索结果，已经有一些标准化家庭资源/根资源的提案。以下是其中一项提案的链接：

https://datatracker.ietf.org/doc/html/draft-nottingham-json-home-06

以下是从提案中获取的响应示例：

     GET / HTTP/1.1
     Host: example.org
     Accept: application/json-home

     HTTP/1.1 200 OK
     Content-Type: application/json-home
     Cache-Control: max-age=3600
     Connection: close

     {
       "api": {
         "title": "Example API",
         "links": {
           "author": "mailto:[email protected]",
           "describedBy": "https://example.com/api-docs/"
         }
       }
       "resources": {
         "tag:[email protected],2016:widgets": {
           "href": "/widgets/"
         },
         "tag:[email protected],2016:widget": {
           "hrefTemplate": "/widgets/{widget_id}",
           "hrefVars": {
             "widget_id": "https://example.org/param/widget"
           },
           "hints": {
             "allow": ["GET", "PUT", "DELETE", "PATCH"],
             "formats": {
               "application/json": {}
             },
             "acceptPatch": ["application/json-patch+json"],
             "acceptRanges": ["bytes"]
           }
         }
       }
     }