带有链接的REST资源表示,与PUT和GET兼容

Question

我被要求设计和实现RESTful API,并且一直在研究最佳实践,但到目前为止,只有一个关于资源表示的愚蠢概念.我发现的大多数可用示例似乎都非常关注使用一系列GET来连接结构的API客户端.

我看过:

http://www.restapitutorial.com/media/RESTful_Best_Practices-v1_1.pdf

http://www.youtube.com/watch?v=HW9wWZHWhnI

在其他在线资源(我限于2个链接抱歉不能列出所有).它们都很棒,但并没有真正解决我的设计问题.

大多数最佳实践文档都提出了两件让我看起来有点冲突的事情:

1)REST服务应将数据关系表示为资源之间的链接

2)来自客户端的"PUT"请求应该是完整的表示,形式与服务器上看到的表示形式相同.

从我的观点来看,问题在于链接以及典型资源中的其他一些属性是只读的,因此无法更新.该服务器可以预期它们按原样运行,如果它认为客户端正在尝试更新它们,则会返回错误.事实上,当我查看JSON中表示的典型资源时,其中大部分是逻辑上不能/不应该替换的数据.例如

{
 "link": { "rel":"self", "href":"http://example/project/12345" },
 "team": {
    "link": { "rel":"self", "href":"http://example/project/12345/team" },
    "title": "The project team"
  },
  "title": "The Big Project"
}

在这里,最多只有两个标题文本可以写入该资源上的客户端(团队成员资格可以通过团队链接进行更改).

因此,我是否应该要求PUT完全按原样包含所有"链接"元素,这些元素纯粹是逻辑和只读的(注意在示例中,团队无法重新链接,因为资源将其定义为团队对于项目 - 在这种情况下可以改变,但对于许多具有更严格的集装箱船的资源类型,这不适用)？

是否有标准模式或反模式用于在REST中表示具有许多链接的资源？我没有被要求提供特定的REST变体,例如HATEOAS,尽管我倾向于在可能的情况下瞄准理论上的"正确性".换句话说,如果"官方"REST将期望客户端将整个资源,链接和所有内容投入,那么这可能就是我要做的.

支持GET和PUT的现实世界复杂的非叶子REST资源的一些示例,因此必须处理这个问题,将非常感激.当我搜索时,我得到了很多意见,并且很多例子显示了GET的工作原理...但到目前为止,我还没有看到一个记录良好的示例,显示PUT除了一个简单的叶子资源(即一个不包含任何链接,除了自我引用之外).

Answer 1

您应该根据您的媒体类型定义放置“完整”表示。如果您正在设计自己的媒体类型，则您的规范应定义哪些部分是可变的，哪些部分是不可变的。例如，Shoji Catalog Protocol 定义了一个旨在包含可变数据的“body”成员：

一般来说，当主体成员存在时，处理器应该期望主体内存在的值可能是可变的（例如，通过 HTTP PUT 或 POST），并且应该期望主体成员之外的任何值都是不可变的；也就是说，（可能）在插入时可写，但在更新时不可写。服务器是免费的，当然可以允许或禁止资源任何部分的可变性。但是“主体”成员的存在强烈暗示了该成员内部和外部的数据的可变性。

这不是一个标准（尽管它对我来说显然很有用，我希望它成为一个标准（眨眼））。请注意，服务器可以自由地对客户端发送的表示进行任何操作；对于任何 HTTP 服务器来说，最强烈的要求是它尝试执行客户端的意图（如果可以且允许的话）。它如何以及在多大程度上做到这一点确实是您的特定应用程序所关心的问题，这就是为什么您在任何有关它的规格中都找不到太多内容的原因。

在实践中，我还没有发现服务器验证链接或表示的其他不可变部分有用；他们只是被忽略了。这可能会导致客户决定他们可以忽略这些。同样，在实践中我没有发现这是一个问题。