不同的资源表示（REST API）答案

【问题标题】：Different Resource Representations (REST API)不同的资源表示（REST API）
【发布时间】：2009-08-18 00:54:03
【问题描述】：

我正在开发一个 REST API，但我有一个关于资源表示的问题。

假设我在 /app/person/{id} URI 下有“人”资源。我需要一个 XML 表示，基本上就是所有对象字段作为根下的 XML 节点。现在，需求表明我们还必须支持另一种由专有模式强制执行的 XML 表示。

我的问题：是否符合 REST 最佳实践来支持同一资源的专有内容类型，如 text/my-type？请注意，两者都是 XML，但格式不同，最重要的是它们不携带相同的信息（例如，一种表示可能包含其他字段，如 modified-since）。

重要！ - 我知道务实和保持简单比指南和“最佳实践”更重要，但我只是想知道这是否是 RESTful 架构下的方式。

【问题讨论】：

如果您在 API 中指定 URI 命名方案（如 /app/person/{id}），那么您的 API 是 RPC，而不是 REST。
@pablo 是的，@Wahnfrieden 确实知道 REST 是什么。问题是许多人试图通过定义一组端点来定义 REST API，就像他们定义 RPC API 一样。 REST API 不能以这种方式工作。 REST API 设计应侧重于媒体类型的定义。端点是什么与客户端和 API 的 RESTful 完全无关。但是，服务器实现确实关心 URL，因此很难让人们在设计时忽略它们。
@Wahnfrieden。我明白你的观点，它有一些优点。不过，我还是不同意。 [我现在要使用一个便宜的技巧并参考更高的权威] Roy Fielding 说：“REST 不要求 URI 是不透明的。在我的论文中出现不透明这个词的唯一地方是我抱怨cookie 的不透明性。事实上，RESTful 应用程序在任何时候都被鼓励使用具有人类意义的分层标识符，以便最大限度地意外使用信息，超出原始应用程序的预期。”
@Pablo 正确。客户端不应该知道 url 结构。作为一个练习，下次你想构建一个 REST 接口时，像做 TDD 一样做。首先创建客户端并为服务器使用存根。让客户端从检索到的表示中获取 URL。您会很快看到客户端并不关心 url 的样子。现在去使用最简单的 url 结构来实现真正的服务器。客户端代码不应更改。
@Pablo 我希望有一些实现 REST 客户端的好例子可以指点您。也许有一天我会抽空尝试写一篇。在那之前，想想网络浏览器是如何让你在一个它一无所知的网站上做这么多事情的。

标签： rest

【解决方案1】：

如果第二种格式只是一种不同的语法（或者可以合理地视为这样），那么将它添加为另一种媒体类型的第二种表示是完全可以的（并且是 RESTful 并符合 REST 最佳实践）。如果您认为差异不仅仅是语法上的，您可能应该创建一个不同的资源。如果您希望能够链接到特定的表示，也是如此（因为如果您想这样做，它需要不同的 URI）。在后一种情况下，您可能还需要考虑一个规范的、与格式无关的资源，它可以返回 303 See Other 并带有指向特定资源的链接。

【讨论】：

【解决方案2】：

是和不是。没有 REST 约束阻止您从同一 URL 返回资源的两种不同表示形式。即使一种媒体类型是专有格式。小心不要让内容变化太大，我听说有些人对此感到非常不安。此外，对于自定义格式，您应该使用供应商子树下的媒体类型

例如应用程序/vnd.companyname.format+xml

但是，返回专有格式并不真正符合 REST 的精神。话虽如此，除了限制偶然的重复使用之外，您可以毫无问题地做到这一点。

【讨论】：

REST 对专有格式没有任何问题 - HATEOS 实际上完美地描述了这种情况。想要与 RESTful 服务交互的客户端只需要知道该服务返回的媒体类型（无论是 jpeg、Atom XML、Word 文档等...）

【解决方案3】：

Content Negotiation 使用 Accept 和 Accept-Encoding 标头构建到 HTTP 中。客户端应用程序应通过设置这些标头来指定它们想要返回的类型。

【讨论】：

这没有回答我的问题......似乎更像是评论而不是答案
他的这个评论的意思是，HTTP 协议具有强大的内置功能，可以处理从同一资源返回的多个表示形式。

【解决方案4】：

如果这些只是 Person 资源的两种不同表示形式，那么您应该为它们提供两种媒体类型。如果可能，请尝试查找和重用标准表示及其媒体类型（请参阅http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven）。两种媒体类型的格式都应为application/type+xml（参见 Darrel 的评论）。

【讨论】：

基于xml的自定义类型命名为application/type+xml。如果您正在创建自己的自定义类型，那么它们通常是在供应商子树下创建的。例如应用程序/vnd.mycompany.mytype+xml
谢谢 Darrel，我已经把“xml”和“type”翻了个遍。
谢谢吉姆，虽然链接坏了
@Darrel 我想知道为什么 xml 没有出现在供应商树之前 - application/xml+vnd.mycompany.mytype ？然后处理任何类型的 XML 的客户端，即使只是一个简单的 XML 美化器，都可以很容易地看到它是一种应用程序媒体类型，并且使用 XML，然后它进一步专门化到供应商特定的空间。这对我来说更有意义，除非内容类型规范指示客户忽略 / 和 + 之间的内容，如果他们不关心供应商特定的专业化或类似的古怪。