REST API 端点命名约定？

Question

我在 REST api 中命名端点时遇到问题。

假设您在客户端有一个 UI，其中 UI 是一个带有文件列表的 table。点击文件时，它将继续从服务器下载所选文件。此外还有一个按钮，单击该按钮将下载所有文件或选定的文件。

因此 API 上的端点可能结构如下...

[获取]Api/Files/{文件名}
- 通过路径中提供的文件名获取单个文件。
[获取]Api/Files
- 获取文件列表，包括：文件名、大小、类型等...
[获取]Api/Files
- 获取文件，以 ZIP 文件形式返回。

如您所见，问题是端点与 Api/Files 的冲突。我希望两个端点都按照我指定的方式进行。但是其中一个需要改变……我想过在最后添加一些东西，但想到的大多是动词。关于如何完成格式化的任何想法？

Answer 1

HTTP/RESTy方式是用Acceptheader指定你想要的响应类型。如果 Accept 为 application/json，则端点可以 return 结果为 JSON，如果 application/zip

，则为 ZIP 文件

在最坏的情况下，您可以检查请求的 Accept header 和 return 或者 JSON 结果或创建 ZIP 文件和 return它与 return File(...).

Produces 属性可用于指定每个操作的内容类型 return，允许您为每个内容类型编写不同的操作。

另一种选择是创建一个 custom output formatter and have ASP.NET itself handle the generation of the ZIP file when the Accept header requests it. This blog post 展示了如何创建一个 Excel 输出格式化程序，当 Accept header 请求这个

Answer 2

I would expect both endpoints to do what I have specified that they do. But one of them needs to change...

正确 - 扩展该想法，您有三个资源（文件内容、可用文件列表、可下载的文件存档），但只有两个名字;所以你至少需要一个名字。

好消息：REST 不关心您对资源标识符使用什么拼写约定，因此您实际上不需要好名称。

/Api/0d660ac6-d067-42c1-b23b-daaaf946efc0

那会很好。机器不在乎。

虽然人类确实在乎；如果我们不试图猜测不同 UUID 的含义，那么查看访问日志或在文档中查找内容会容易得多。

mostly verbs come to mind

动词很好。请注意，这些 URI 的工作方式与您预期的完全一样：

The HTTP/RESTy way is to specify the response type you want with the Accept header.

这里可能不是您想要的。有效目标uri是主缓存键；当我们 invalidate 缓存条目时，所有表示都将失效。如果这不是您想要的文件列表和可下载 zip 之间的关系，那么让它们共享资源标识符将是不愉快的。

Accept 当您对同一事物有多种表示时更有意义（即文件列表，但表示为 HTML、JSON、文本、XML, 等等).

您可能还会考虑这些标识符在访问日志中的样子；文件列表和 zip 应该使用相同的 URI 记录吗？您是否希望通用日志解析工具（如警报系统）将两种不同类型的提取视为等效？

Answer 3

查看不同的答案并进行测试，我认为最好的答案就是使用不同的端点名称。所以我现在去了...

[获取]Api/Files/{文件名}
- 通过路径中提供的文件名获取单个文件。
[获取]Api/Files
- 获取文件列表，包括：文件名、大小、类型等...
[获取]Api/Files/存档
- 获取文件，以 ZIP 文件形式返回。

虽然不完美，但很有道理。

替代方案可能是...

[获取]Api/Files/邮编但我认为这不是很好。由于端点永远不应该改变，我可能想在某个时候从 zip 改变它...

REST API 端点命名约定？

REST API Endpoint Naming Conventions?

c#

api

rest

model-view-controller

asp.net-core