向 API 请求“/cats”会返回猫的集合,而请求“/cats/123”会返回 id 为“123”的猫
我的问题是:当请求'/'(API的根)时应该响应什么?
也许是包含 API 中所有集合名称的索引?
这个问题可能没有客观的答案,但一个很酷的 API 应该是可浏览的。这意味着,给定一个起始 URI,应该可以“发现”完整的 API,因此拥有一个链接到 API 的所有不同部分的根资源肯定会有所帮助。
即使所有服务都是单独的应用程序(想想微服务),我仍然会创建一个服务来为所有服务提供“开始”链接,从而真正为整个应用程序提供一个入口点。
我的意思是,不仅供人类浏览,而且客户端也会从第一个 URI 开始。总是,除非使用以前状态的书签(并且在给定重定向或未找到时需要维护这些书签)。
我不知道这是否有一个固定的约定。这取决于您想要提供什么以及您的安全顾虑是什么。您可以考虑在 REST API 中返回有效对象的列表。或者,如果您不想向任何人透露该信息,请考虑返回 204 或 404。
尽管这个讨论已经消亡多年,但考虑到在谷歌搜索该主题时它仍然显示为热门搜索结果,已经有一些标准化家庭资源/根资源的提案。以下是其中一项提案的链接:
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"]
}
}
}
}