REST API 接受标头 json/pdf

Question

我目前正在使用 API，我认为这是对 REST API 的错误实现。

我们有以下端点

1. GET v1/{organizationId}/invoices
2. GET v1/{organizationId}/invoices/{guid}

当您获取第一个端点时，您将获取所有发票，但如果您获取第二个端点，但没有 Accept: Application/json 标头，您将获得来自第一个端点的响应。

提供 API 的公司表示，这样做的原因是因为第二个端点可以同时提供 JSON 和 PDF 输出，看起来就像 PDF 一样

GET v1/{organizationId}/invoices/{guid}/pdf

此外，如果发送格式错误的guid，您会得到一个完整的 HTML 404 错误页面，而不是空白页面或错误消息。

总结一下

1. 2. 端点处理得当​​吗？
2. 将 PDF 作为 JSON/XML 之类的输出是否有效？
3. 不应该是一个新的端点吗？
4. 是否允许 HTML 作为错误响应，即使是格式错误的请求？

Answer 1

有些人不喜欢将基于 REST 的问题分类为“正确”和“错误”，但我还是会继续：

1. 不，第二个资源应始终返回第二个资源的表示形式，即发票，而不是发票集合。

2. 是的，可能返回同一“事物”的多个表示是完全可以的。可以想象，发票可以同时返回 json 和 pdf，并且可以根据“Accept”标题选择正确的发票。

3. 不，它不应该是一个新的“端点”，因为这些“东西”不是“端点”，而是资源。发票是一种资源，json 文档只是资源的“表示”。

4. 是的，错误响应可以包含正文，服务器可以轻松发送任何表示形式。服务器当然应该使用来自客户端的“Accept”标头来定位自己，但这不是必须的。

几点说明：不能GET 带有错误guid 的发票，因为这些资源应该从集合资源链接。当客户端跟随链接（应该如此）时，应该没有办法使用错误的 guid 跟随链接。

返回完全不同的资源（发票集合而不是发票）是错误的，但同一资源有多个表示是可以的。如果没有“Accept”标头，服务器应该选择一个，或者指出406 Not Acceptable。

一个小点：mime-type 不应该是application/json，因为那你怎么知道它是发票呢？它应该类似于：application/vnd.someprovider.invoice+json。这些天没有人关心哑剧类型，但我只是为了完整起见而提到它。