HTTP GET 上的部分对象答案

【问题标题】：Partial object on HTTP GETHTTP GET 上的部分对象
【发布时间】：2019-12-24 17:02:09
【问题描述】：

我们收集了一些文件：

class Document {
id;
title;
someContent;
creator;
...
}

需要实现 REST API，在第一种情况下，返回包含所有字段（“id”、“title”、“someContent”等）的所有文档。在第二种情况下，返回所有文档，但仅返回部分字段（仅“id”和“title”）。

哪种方式最好？使用查询参数“字段”在一个端点中实现它是个好主意吗？还是将它们分开到不同的端点更好？我也可以使用 206 状态码吗？是否有任何“最佳实践”来实现此功能？

例如我可以这样做（但我不确定它是否正确）：

GET /documents (200 status code)
GET /documents?field=id&filed=title (206 status code)

因此，“字段”是可选的查询参数，它只是指示我们需要返回的字段。

在第一次 Get 中，将返回所有字段。例如：[{id: "5F1AB3", title: "Document 1", creatur: "John", ...}, {...}]。第二种，只有两个字段的 JSON：ID 和标题。响应如下所示：[{id: "5F1AB3", title: "Document 1"}, {...}]。

【问题讨论】：

标签： rest api architecture

【解决方案1】：

哪种方式最好？

您可能需要两种不同的资源，就像全尺寸图像和缩略图是不同的资源一样。

如果它们是不同的资源，那么我们应该会看到两个不同的标识符。

请注意，如果您尝试为资源添加书签或与其他人共享您的书签，这正是您作为客户想要的。

GET /documents
GET /documents?field=id&field=title

那些标识符很好。 REST 很少关心您用来区分一个标识符和另一个标识符的拼写约定。请注意，查询是标识符的一部分——就通用组件而言，这是两个不同的标识符，这两个资源可能根本不相关！

206 Partial Content 不是一个好主意； 206 的语义与 Range Requests 耦合，这不适合您正在做的事情。

【讨论】：