如何设计 REST API 以允许返回带有元数据的文件 [英] How to design a REST API to allow returning files with metadata

问题描述

假设我正在设计一个 REST API，并且我需要客户端能够获取带有元数据的文件.设计资源/操作的好方法是什么?

Suppose I'm designing a REST API and I need the clients to be able to obtain files with metadata. What is a good way to design the resources / operations?

我想到了一些想法:

• 单个资源(即 GET/files/{fileId})，它返回包含文件和带有元数据的 JSON/XML 结构的多部分响应.我有一个感觉这不是一个很好的方法.例如，您不能使用客户端的 Accept 标头来确定他们想要 XML 还是 JSON 元数据表示，因为在这两种情况下响应类型都是多部分的.

• A single resource (i.e. GET /files/{fileId}), which returns a multi-part response containing both the file and a JSON/XML structure with metadata. I have a feeling that this is not a very good approach. For example, you cannot use the Accept header for the clients to determine if they want a XML or a JSON metadata representation, since the response type would be multi-part in both cases.

两个资源(即 GET/files/{fileId} 和 GET/files/{fileId}/metadata)，其中第一个返回文件本身，第二个返回 JSON/XML 结构元数据. 可以有从元数据到文件的链接.但是，如何将指向元数据的链接与文件一起发送?

Two resources (i.e. GET /files/{fileId} and GET /files/{fileId}/metadata), where the first one returns the file itself and the second one a JSON/XML structure with metadata. There can be a link from the metadata to the file. However, how do I send a link to the metadata along with the file?

推荐答案

我建议使用您提出的第二个想法.这是大多数主要网络驱动器(Box、Dropbox、Google Drive 等)使用的策略.它们通常具有截然不同的 URL，因为它们将内容和元数据存储在不同的位置.

I would suggest using the second idea you presented. This is the strategy used by most of the major web drives (Box, Dropbox, Google Drive, etc). They often have a significantly different URL because they store content and metadata in disparate locations.

您可以将链接标头添加到文件响应中，并带有指向元数据的链接.RFC 5988 中描述了链接标头.当前注册的链接关系集是这里.从袖口上看，describeBy 关系似乎在这里是合适的.

You can add a Link header to the file response with a link to the metadata. Link headers are described in RFC 5988. The set of currently-registered link relations is here. Off the cuff, it seems that the describedBy relation is appropriate here.

这篇关于如何设计 REST API 以允许返回带有元数据的文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！