具有相同对象但轻量级的 REST API

Question

我们正在构建一个 REST API，我们希望返回相同的对象，但一个调用是“轻量级”版本（没有所有字段）

最佳做法是什么？

第一种情况

• 完整版：http://api.domain.com/myobject/{objectId}
• 轻量版：http://api.domain.com/myobject/{objectId}?filter=light

第二种情况

• 完整版：http://api.domain.com/myobject/{objectId}/details
• 轻量版：http://api.domain.com/myobject/{objectId}

第三种情况

• 完整版：http://api.domain.com/myobject/{objectId}?full=true
• 轻量版：http://api.domain.com/myobject/{objectId}

第四种情况？

欢迎提供任何指向 REST API 文档资源的链接！

谢谢。

Answer 1

这应该通过内容协商来处理，这就是它的用途。内容协商是客户端如何请求它想要查看的资源的哪种表示。以图片为例：image/x-canon-cr2, image/jpeg, image/png。

表面上都是相同的图像，但格式不同。

因此，这是您真正希望用于资源“精简”版本的机制。例如，您可以使用：

• 主版本的“application/xhtml+xml”
• "application/xhtml+xml; lite" 用于轻量级版本

所以，对于完整的资源：

GET /resource
Accept: application/xhtml+xml

对于精简版

GET /resource
Accept: application/xhtml+xml; lite

两者皆可，但更喜欢精简版：

GET /resource
Accept: application/xhtml+xml;lite, application/xhtml+xml

（更具体的说明符，即带有 ;lite 的说明符，比普通的 applciation/xhtml+xml 具有更高的优先级。）

如果您愿意，但更喜欢完整版：

GET /resource
Accept: application/xhtml+xml;lite;q=0.1, application/xhtml+xml

那些没有品质因数的默认为 1.0，因此 0.1 小于 1.0，如果在 lite 版本上可用，您将获得完整版本。

附录：

Accept 上的 q 因子有效地用于显示客户的偏好。它用于确定客户端接受的媒体类型列表的优先级。它说“我可以处理这些媒体类型，但我更喜欢 a over 和 b over c”。

JPEG 与 PNG 与精简版与完整版没有什么不同。 JPEG 看起来像原始 PNG 的事实是一种视觉错觉，数据大不相同，它们有不同的用途。 JPEG 不是“低质量”，而是不同的数据。这是“缺失的领域”。例如，如果我想要图像大小，JPEG 会像 PNG 一样为我提供该信息。在这种情况下，它的质量足以完成任务。如果这还不够，那么我不应该要求它。

我可以保证，如果我有一个只能处理 PNG 并请求 JPEG 的客户端，那么该程序将无法与它“正常工作”。如果我儿子想要鸡手指，而我给他菠菜奶油，就会有问题，尽管这两者都是资源/晚餐的代表。

“application/xhtml+xml;lite”表示就是这样——一种表示，它不是资源本身。这就是为什么使用表示这个词的原因。这些表示都是对实际资源的简单投影，实际资源是服务器上的某个虚拟实体，以某种未定义的方式在内部实现。

有些表示是规范的，有些则不是。

表示通过媒体类型表现出来，媒体类型通过 Con-neg 和 ACCEPT 标头处理。如果您无法处理代理，请不要要求。

这是一个否定问题。

我不知道“媒体播放器”与这个讨论有什么关系。

Answer 2

第一种情况和第三种情况的优点是一个 url 用于单个资源，而查询字符串用于请求该资源的特定视图。在它们之间进行选择是个人喜好问题，但我倾向于默认获取所有数据并保存用于查看子集的选项。