rest - 用于创建和更新资源的超媒体友好 REST 模式

Question

我正在尝试设计一个充分利用超媒体的 RESTful 服务。
最好，用户代理应该只知道根 URI，以便能够探索服务的所有功能 - 也就是说，我希望它位于 maturity model 中的第 3 级。 .

现在，用户代理应该能够创建一些资源并在以后编辑它们。在创建/编辑时，用户代理需要访问一些其他资源/枚举。

foo 资源:

{
    "category" : "category chosen from an enumeration of possible categories",
    "color" : "color chosen from an enumeration of possible colors",
    "aRelatedResource" : "resource identifier from chosen from a collection"
}

鉴于前面提到的要求，我提出了以下模式:

有一个 fooRoot 资源:

{
    // no properties, only links
    "_links" : { 
        "foos" : { "href" : "URI-to-foos" },
        "fooCreator" : { "href" : "URI-to-plain-fooWriter" }
    }
}

包括指向 的链接fooWriter 在 foo 资源:

foo 资源:

{
    "category" : "category chosen from an enumeration of possible categories",
    "color" : "color chosen from an enumeration of possible colors",
    "aRelatedResource" : "resource identifier from chosen from a collection",
    "_links" : {
        "self" : {...},
        "fooEditor" : { "href" : "URI-to-fooWriter-initialized-for-current-foo" }
    }
}

A fooWriter 如下所示:

{
    "fooPayload" : {
        "category" : "NULL or pre-initialized",
        "color" : "NULL or pre-initialized",
        "aRelatedResource" : "NULL or pre-initialized"
    },
    "_links" : {
        "fooPayloadDestination" : { "href" : "URI-to-foos-or-foo" },
        "categoryEnum" : { "href" : "URI-to-categories" },
        "colorEnum" : { "href" : "URI-to-colors" },
        "availableResourcesToRelateWith" : { "href" : "some-other-URI" },
        ....
        .... and even something useful for pre-validation etc.
        "validator" : { href : "URI-to-some-resource-or-service" }
    }
}

综上所述，任何可以创建和编辑的资源都可能有一个关联的 作家 资源。
通过 GET-ting 编写器，用户代理可以非常方便地创建/编辑资源。
有效载荷 嵌入在 writer 中的被 POST-ed 到它的 目的地瞧:)

此外，应该有一个根容器保存指向新资源的资源及其编写者的链接(参见上面示例中的 fooRoot )。



问题是...

...上面描述的模式有一个众所周知的名字吗？
...有没有更好的方法来解决创建/编辑问题，在创建/编辑时需要相邻资源并且第三级成熟度仍然“保持”？

一些引用资料:

The Hypermedia scale

Richardson Maturity Model

A REST API leveraging the hypermedia quite well

Answer 1

你的描述让我想起了create and edit form link relations .但是，如果您正在构建 API，它的使用是相当有限的，因为无论它是如何定义的，您都需要有人对其进行编程。

在我看来，组织上面给出的示例的最简单方法是定义一个根菜单，如下所示:

GET / HTTP/1.1
Accept: application/hal+json
----
HTTP/1.1 200 OK
Content-Type:application/hal+json

{
    "_links" : { 
        "plants" : { "href" : "/plants" }
    }
}

plants关系将保存由给定媒体类型定义的植物资源集合(假设它是 application/vnd.biology-example-org.plant ):

GET /plants HTTP/1.1
Accept: application/hal+json
----
HTTP/1.1 200 OK
Content-Type:application/hal+json

{
    "_links" : { 
        "self" : { "href" : "/plants" },
        "plant": [
          {
            "href" : "/plants/parsnip",
            "title" : "The Parsnip",
            "type" : "application/vnd.biology-example-org.plant+json"
          }
        ]
    }
}

要将新植物添加到与欧洲防风草相关的集合中，请发布到 plants收集资源并通过其链接与 parnsip 相关:

POST /plants HTTP/1.1
Content-Type: application/vnd.biology-example-org.plant+json

{
    "title" : "The Carrot - a cousin of the Parsnip",
    "category" : "vegetable",
    "color" : "orange",
    "related" : [ "/plants/parsnip" ]
}
----
HTTP/1.1 201 Created
Location: http://biology.example.org/plants/carrot

要随后修改胡萝卜，请向返回的 URL 发出 PUT:

PUT /plants/carrot HTTP/1.1
Content-Type: application/vnd.biology-example-org.plant+json

{
    "title" : "The Carrot - the orange cousin of the Parsnip",
    "category" : "vegetable",
    "color" : "orange",
    "related" : [ "/plants/parsnip" ]
}
----
HTTP/1.1 200 OK

上面的示例使用超文本应用程序语言 (HAL) 使用 JSON 来传达“第 3 级”REST 语义。 HAL 简单但非常强大。我真正喜欢的约定之一是使用关系名称作为 URI，当取消引用时，它直接指向有关该关系及其可以返回的资源的文档。

如果您想使用这样的实时 API，我强烈建议您查看 HALtalk ，这是 HAL 的现场演示 API。