REST API 并提供二进制资源 [英] REST API and delivering a binary resource

问题描述

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

What is the convention to deliver a binary resource (like a pdf file) with a REST API? Do you just return a URL to the resource in your JSON or XML response, e.g., {"url" : "http://example.com/document.pdf"} ?

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

I'm trying to understand the difference between a URI and URL and keep with a RESTful philosophy. Admittedly, this is new to me so I may be misunderstanding some things.

推荐答案

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

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

如果您主要返回 JSON，那么 url 条目是一种常见的方法.如果你正在做一些更像 HTML/XML 的事情，那么像 <link> 元素和一个好的 rel 属性会很有意义.

If you're returning mostly JSON, then a url entry is a common way to go. If you're doing something more HTML/XML-ish, then something like a <link> element with a good rel attribute makes a lot of sense.

显然，如果客户端向您提供给他们的直接 URL 发出 GET 请求，那么您应该将文件发送给他们，除非他们发送了一堆有效阻止您访问的内容协商标头满足他们的要求.在这种情况下，406 Not Acceptable 响应(或 官方定义) 很有道理.

Obviously, if the client makes a GET request to the direct URL you gave them, then you should send them the file, unless they sent a bunch of content-negotiation headers that effectively preclude you from fulfilling their request. In that case, a 406 Not Acceptable response (or the official definition) makes a lot of sense.

如果您的问题有其他含义，请澄清.

If you meant something else by your question, please clarify.

首先:忽略 URL 与 URI.与此无关.完全没有.

First: ignore URL vs. URI. It doesn't have anything to do with this. At all.

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

Next: If your problem is not "How do I link to a resource" (which might be affected by the stuff I'm about to discuss), but "What if my resource is just a PDF file", you have all sorts of options for addressing it. First off, you need to step back and think more abstractly (a little). Your resource is almost certainly not "a PDF file". It's "a file uploaded by a user", or "a PDF version of a report that I generate", etc.

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

In the first case, you probably don't have any representation of the resource beyond the binary they sent you, which is totally fine. You probably won't need to perform any sort of content-negotiation when you receive a GET to the URL for that resource. Just send them the file, subject to the caveats about 406 I mention above.

在第二种情况下，您可能拥有此资源的各种表示形式:CSV、HTML、LaTeX，您可以随意命名.在这种情况下，当您收到资源 URL 的 GET 时，您确实需要进行一些内容协商，以便您知道是否将 PDF 文档发送给他们， 或者是其他东西.您可能拥有资源的 JSON 表示形式，它只是用于生成 PDF 的原始数据.

In the second case, you might have all sorts of representations of this resource: CSV, HTML, LaTeX, you name it. In this case, when you receive a GET to the URL for the resource, you do need to do some content-negotiation, so you know whether to send them the PDF document, or something else. It's possible that you might have a JSON representation of the resource that is just the raw data you use to generate the PDF.

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

In either case, it would be unexpected if you had a representation that was strictly metadata about the resource. If needed (often it is, sometimes it isn't), explicit, external metadata (as opposed to metadata embedded within the binary resource, such as author and title info in PDFs) is most commonly modeled as a separate resource.

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

Finally, as @monitorjbl says: you probably don't want to embed the binary data directly in a text format such as JSON or XML. There are ways of doing it, often involving the words "base64-encoded", but it's usually not the best approach. In general, you shouldn't mix binary data and text data.

这篇关于REST API 并提供二进制资源的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！