REST/HATEOAS API 的入口点？

Question

我已经开始设计 API，并决定尝试使其符合 REST/HATEOAS。 API 的入口点应该是什么？

GET / 似乎很常见，但从我读到的内容来看，使用OPTIONS / 在逻辑上可能更有意义，因为/ 实际上没有用于检索的资源。

我在这里给出了这两个例子，使用 JSON 的 HAL 语法作为超媒体格式。

获取 /

请求：

GET / HTTP/1.1
Host: example.com

回应：

HTTP/1.1 200 OK
Date: …
Content-Type: application/json;charset=utf-8
Content-Length: 143

{
    "_links": {
        "self": {
            "href": "/"
        },
        "penguins": {
            "href": "/penguins"
        }
    }
}

选项/

请求：

OPTIONS / HTTP/1.1
Host: example.com

回应：

HTTP/1.1 200 OK
Date: …
Allow: OPTIONS
Content-Type: application/json;charset=utf-8
Content-Length: 143

{
    "_links": {
        "self": {
            "href": "/"
        },
        "penguins": {
            "href": "/penguins"
        }
    }
}

Answer 1

在这种简单的情况下，我建议使用 Link 标头：

HTTP/1.1 200 OK
Date: …
Link:</likeapenguinbutopaque>;rel=penguin;type=image/jpeg

“rel”属性的使用还允许指定与链接引用的目标资源的关系。请注意，“rel”的语义必须在当前资源的上下文中进行解释。为了说明这一点，让我们点击链接。应该返回企鹅的图片，以及以下链接：

Link : <>; rel=wing;type=image/jpeg

这里的“翅膀”关系很明确：它是当前资源（企鹅）与其 OWN 翅膀（不是另一只企鹅的翅膀）之间的关系。这就是 HATEOAS 的魔力（和冗长）：每个链接仅在特定的资源上下文中才有意义。 所有这一切都是为了克服在浏览时在给定场合返回的单个文档中描述所有资源树的诱惑。这将是邪恶的，呃，不是 HATEOAS...

另请注意，此处在交换 JPEG 图像时实现了 HATEOAS，其媒体类型不是超媒体。链接标题，普遍且足够丰富将完成这项工作。 假设您拥有的一些企鹅可以更新：

Link: <>;rel=wing;allow=PUT;type=image/jpeg

将在给定的可更新企鹅的精确上下文中发出信号。

Answer 2

OPTIONS 请求的响应仅描述您请求的资源的选项，即/。 GET / 通常会提供更多信息，然后让响应正文中每个链接的链接关系告诉您可以对链接的资源采取哪些操作。

此外，对OPTIONS 的响应是不可缓存的，这可能非常重要，尤其是在涉及静态内容（如链接菜单）时。