REST API 并提供二进制资源

Question

使用 REST API 交付二进制资源(如 pdf 文件)的约定是什么？您是否只是在 JSON 或 XML 响应中返回资源的 URL，例如 {"url": "http://example.com/document.pdf"} ？

我试图理解 URI 和 URL 之间的区别，并遵循 RESTful 哲学。诚然，这对我来说是新的，所以我可能会误解一些事情。

Answer 1

本节假设您的意思是:我如何告诉用户在哪里可以找到二进制资源

URI 和 URL 之间的区别与二进制与非二进制数据类型 ( see also ) 没有任何关系。

如果您主要返回 JSON，则返回 url进入是一种常见的方式。如果你正在做一些更像 HTML/XML 的事情，那么像 <link>元配好rel属性很有意义。

显然，如果客户端发出 GET请求您提供给他们的直接 URL，然后您应该将文件发送给他们，除非他们发送了一堆内容协商 header ，这些 header 有效地阻止了您满足他们的请求。在这种情况下， 406 Not Acceptable 响应(或 the official definition )很有意义。

如果您的问题是其他意思，请澄清。

一个漫无边际的“像这样做”部分

第一:忽略 URL 与 URI。与此无关。在所有。

下一篇:如果您的问题不是“我如何链接到资源”(这可能会受到我即将讨论的内容的影响)，而是“如果我的资源只是一个 PDF 文件怎么办”，那么您有各种各样的解决它的选项。首先，你需要退后一步，更抽象地思考(一点点)。您的资源几乎肯定不是“PDF 文件”。它是“用户上传的文件”，或“我生成的报告的 PDF 版本”等。

在第一种情况下，除了他们发送给您的二进制文件之外，您可能没有任何资源表示，这完全没问题。当您收到 GET 时，您可能不需要执行任何类型的内容协商。到该资源的 URL。只需将文件发送给他们，但须遵守有关 406 的警告。我上面提到了。

在第二种情况下，您可能拥有此资源的各种表示形式:CSV、HTML、LaTeX，等等。在这种情况下，当您收到 GET到资源的 URL，您确实需要进行一些内容协商，以便您知道是向他们发送 PDF 文档还是其他内容。您可能有资源的 JSON 表示，它只是您用来生成 PDF 的原始数据。

在任何一种情况下，如果您的表示是关于资源的严格元数据，那将是出乎意料的。如果需要(通常是，有时不是)，显式的外部元数据(与嵌入在二进制资源中的元数据相反，例如 PDF 中的作者和标题信息)最常被建模为单独的资源。

最后，正如@monitorjbl 所说:您可能不想将二进制数据直接嵌入到文本格式中，例如 JSON 或 XML。有很多方法可以做到这一点，通常涉及“base64-encoded”这个词，但这通常不是最好的方法。通常，您不应混合二进制数据和文本数据。