数据格式的 REST api 端点命名

Question

只是想知道在使用不同的数据格式时，关于命名 REST api 端点的每个人的意见。

API 示例

• /api/applications - 获取所有应用程序的列表
• /api/applications/{applicationId} - 获取特定的应用程序详细信息
• /api/applications/{applicationId}/topics - 获取特定应用程序的所有主题

问题

多个消费应用程序可能希望以不同格式交付数据 - 例如列表、树和可能不同的详细程度/详细程度。在 RESTful API 中表示它的最佳方式是什么？

可能的解决方案

不同的端点名称。不喜欢这样，因为它感觉很脏，混合了端点和数据类型：

• /api/applications/{applicationId}/topics
• /api/applications/{applicationId}/detailedTopics
• /api/applications/{applicationId}/topicHierarchy

子路径。不喜欢这样，因为它似乎打破了 RESTful 命名约定。我希望 /topics/{topicId}:

• /api/applications/{applicationId}/topics/details
• /api/applications/{applicationId}/topics/list
• /api/applications/{applicationId}/topics/hierarchy

查询字符串。这似乎是最好的解决方案，但我仍然不是 100% 满意：

• /api/applications/{applicationId}/topics?detail=overview
• /api/applications/{applicationId}/topics?format=list
• /api/applications/{applicationId}/topics?format=tree

很想听听您的一些想法！谢谢！

Answer 1

如果不同的“格式”有根本不同的数据，我个人会有不同的端点。

如果“格式”表示相同的数据，但只是组织方式不同，则解决此问题的标准方法是通过接受标头。

例如，如果您有一个/topics 端点，它支持csv 格式和两种json 格式，我会使用：

Accept: text/csv
Accept: application/vnd.ross.list+json
Accept: application/vnd.ross.hierarchy+json

Answer 2

其中很多是个人喜好，什么对你有用。您不一定会问这个问题，但就个人而言，我更喜欢单一端点，因为您更有可能拥有一个处理单个实体的端点而不是它们的列表。

• GET: /api/applications - 应用程序列表
• GET: /api/applications/{id} - 获取单个应用程序
• POST：/api/applications - 创建单个应用程序
• PUT：/api/applications - 编辑单个应用程序
• PATCH：/api/applications - 编辑单个应用程序
• DELETE: /api/applications - 删除单个应用程序

就主题之类的内容而言，我会将其移至自己的端点

• GET: /api/topics?application={applicationId} - 特定应用程序的主题列表

这样可以使您的端点保持较小，并让您可以根据需要添加其他参数。

我不确定整个细节和格式参数是关于什么的，但如果格式是指内容类型，您可以将其作为查询参数（如文件扩展名）进行，或者将其传递给请求标头。

• /api/appications/{id}.json
• /api/appications/{id}?format=json
• /api/appications/{id} 在请求标头中带有 Accept: application/json。