REST API - 如何查询链接发现? [英] REST API - How to query for links discovery?

问题描述

假设我有一个 RESTful HATEOAS API，它有 /posts 端点，它列出了带有查询快捷方式 /posts/new 的帖子.如何查询 API 以发现 /posts/new?

Suppose I have a RESTful HATEOAS API which has /posts endpoint which lists posts with a query shortcut /posts/new. How do I query the API to discover /posts/new?

我的想法:

1) 查询 /posts 并从 _links 属性获取链接(并且列出的实体是必要的开销):

1) Query /posts and get links from _links attribute (and the entities listed are necessary overhead):

GET /posts

{
  "docs": [
    ...
  ]
  "_links": {
    "new": { "rel": "posts", "href": "/posts/new" }
  }
}

2) 在 API 根目录中提供此内容以及资源列表:

2) Provide this in the API root together with list of resources:

GET /

{
  "resources": {
    "posts": {
      "_links": {
        "self": { "rel": "posts", "href": "/posts" }
        "new": { "rel": "posts", "href": "/posts/new" }
      }
    }
  }
}

3) 我不应该使用 /posts/new 查询，而是使用 /posts 和查询参数.但是，如果我更改服务器逻辑，我也必须更改客户端逻辑，这将是服务-客户端耦合.例如:

3) I should not use the /posts/new query and instead use /posts and query params. However, if I change my server logic I would have to change client logic too and that would be serve-client coupling. For example:

• 客户端将通过某种方式提供参数 timestamp > 来请求新消息.(今天 - 30)
• 我引入了 draft 属性并改变了我的想法，即新的只是带有 timestamp > 的帖子.(今天 - 30) &&草稿 = 假
• 我必须更改客户端以添加草稿约束

• New messages will be requested by client by somehow providing parameter timestamp > (today - 30)
• I introduce draft property and change my idea that new are only the posts with timestamp > (today - 30) && draft = false
• I have to change client to add drafts constraint

注意:帖子只是我一般要求的一个例子.

Note: posts is just an example I am asking in general.

推荐答案

在 REST 架构中 URI 应该通过其附带的链接关系名称来发现.将上面的示例解释为 HAL URI /post/new 有一个new 的链接关系名称.链接关系名称为 URI 提供语义，允许客户端确定何时调用这些 URI.HAL 只是少数支持 HATEOAS 的基于 JSON 的媒体类型之一.有进一步的媒体类型可提供类似的语法和功能略有不同的作业.

In a REST architecture URIs should be discovered via their accompanying link-relation name. On interpreting your examples above as HAL the URI /post/new has a link-relation name of new. Link relation names provide semantics to URIs which allow clients to determine when to invoke these URIs. HAL is just one of a handful JSON-based media types that support HATEOAS. There are further media-types available that provide a similar job with slightly different syntax and capabilities.

收到这样的文档后，客户端将解析消息并为包含实际内容的消息构建一些上下文，包括附加元数据，如链接和进一步嵌入的数据.如果它想检索最新帖子的列表，它基本上需要从前面提到的上下文中查找表达意图(在您的情况下为 new)的键(链接关系名称)以检索分配的值 (URI).客户端如何维护此上下文是一些实现细节.它可能会构建一个树状图，以便更轻松地查找链接关系"键及其值 (URI)，或者使用一些完全不同的方法.

Upon receiving such a document a client would parse the message and build some context for the message containing the actual content including additional metadata like links and further embedded data. If it wants to retrieve the list of the most recent posts it basically needs to look up the key (link-relation name) that expresses the intent (new in your case) from the before-mentioned context in order to retrieve the assigned value (URI). How a client maintains this context is some implementation detail. It might build up a tree-map for easier lookup of "link-relation" keys and their values (URIs) or use some totally different approach.

需要以某种方式提供使用什么密钥的知识.当链接关系表达某些语义时，它们需要在某处指定.这可能发生在行业标准或媒体类型定义中.IANA 维护标准化链接关系名称及其语义.在检查列表时，根据您的规范，最可能的匹配项是 current，它被定义为

The knowledge what key to use needs to be present somehow. As link relations express certain semantics they need to be specified somewhere. This can happen in industry standards or media-type definitions. IANA maintains a list of standardized link-relation names and their semantics. On examining the list probably the most likely match according to your specification is current which is defined as

指包含资源集合中最新项目的资源.

Refers to a resource containing the most recent item(s) in a collection of resources.

因此，我建议将链接关系名称从 new 更改为 current.

I'd therefore propose to change the link-relation name from new to current.

这篇关于REST API - 如何查询链接发现?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！