REST API并提供二进制资源

Question

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

我试图理解URI和URL之间的区别,并保持RESTful哲学.不可否认,这对我来说是新的,所以我可能会误解一些事情.

Answer 1

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

URI和URL之间的区别与二进制数据类型与非二进制数据类型无关(另请参见参考资料).

如果你主要返回JSON,那么一个url条目是一种常见的方式.如果你正在做更多的HTML/XML-ish,那么像<link>具有良好rel属性的元素之类的东西就会很有意义.

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

如果您的问题意味着其他问题,请澄清.

漫步"喜欢这个"部分

第一:忽略URL与URI.它与此没有任何关系.完全没有.

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

在第一种情况下,您可能没有超出他们发送给您的二进制文件的任何资源表示,这是完全正常的.当您收到GET该资源的URL 时,您可能不需要执行任何类型的内容协商.只需向他们发送文件,但需遵守406上面提到的警告.

在第二种情况下,您可能拥有此资源的各种表示形式:CSV,HTML,LaTeX,您可以对其进行命名.在这种情况下,当您收到GET该URL的资源,你就需要做一些内容的谈判,所以你知道是否给他们的PDF文档,或别的东西.您可能拥有资源的JSON表示,该表示只是用于生成PDF的原始数据.

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

最后,正如@monitorjbl所说:您可能不希望直接以文本格式(如JSON或XML)嵌入二进制数据.有办法,通常涉及"base64编码"这个词,但它通常不是最好的方法.通常,您不应混合二进制数据和文本数据.

Answer 2

是否使用二进制文件,您的REST资源应该用超媒体类型来描述.

• 如果您的REST客户端以msgpack格式PUT/POST资源,则REST服务器仍然可以读取此消息并更新/创建资源.那么为什么不呢.
• 如果您的REST客户端以PDF格式PUT/POST资源,我猜你将无法提取正确创建/更新资源所需的所有信息.所以不行.

在最后一种情况下,您可能正在处理类似"Google驱动器"的服务:这些PDF本身不是您的资源,应该由您的实际资源链接(即URL应该在您的资源中).

即使Google Drive可能不是完美的REST API (API参考),它也会处理JSON资源和实际的二进制文件.