资源集合之间的REST API设计链接 [英] REST API Design links between collections of resources

问题描述

我一直在琢磨定义具有相互依存资源集合的正确的方法。

I have been pondering the correct method of defining resource collections which have interdependence.

例如，让我们考虑，文件和意见，这是通过URI的独立访问：

For instance, lets consider "documents" and "comments" which are independently accessible via the URI's:

/documents/{doc-uri}
/comments/{comment-id}

然而，我们通常希望的有关特定文档的评论集合。它创建围绕应如何archetected一个设计问题。

However, we typically want the collection of comments related to a specific document. Which creates a design question around how this should be archetected.

我可以看到几个主要选项：

I can see a few main options:

1）供应的集合URI文档URI征求意见后，

1.) Supply an collection uri after the document uri for comments

GET /documents/{doc-uri}/comments/

2）提供一个参数来收集意见通过文件选择

2.) Provide a parameter to the comments collection to select by document

GET /comments/{comment-id}?related-doc={doc-uri}

3）。使用内容协商要求的相关评论通过Accept头被退回。

3.) Use content negotiation to request the related comments be returned via the Accept header.

// Get all the comments for a document
GET /documents/{doc-uri} Accept: application/vnd.comments+xml
// Create a new comment
POST /documents/{doc-uri} Content-Type: application/vnd.comment+xml <comment>...</comment>

方法1具有自动把注释在文档的上下文中的优点。它创建，更新和删除使用POST / PUT意见时，也不错。但是它不提供一个文档的上下文以外将注释全局访问。所以，如果我们想要做了系统，我们需要方法＃2。所有评论搜索

Method 1 has the advantage of automatically putting the comments in context of the document. Which is also nice when creating,updating and deleting comments using POST/PUT. However it does not provide global access to comments outside the context of a document. So if we wanted to do a search over all comments in the system we would need method #2.

方法2提供了许多相同的好处＃1，但没有创建一个文档上下文的注释是没有意义的。由于意见必须明确相关的文档。

Method 2 offers many of the same benefits as #1, however creating a comment without the context of a document makes no sense. Since comments must explicitly be related to a document.

方法3是从GET和POST /创造的角度来看有趣的，但得到还挺多毛与更新和删除。

Method 3 is interesting from a GET and POST/create perspective, but gets kinda hairy with update and delete.

我可以看到赞成的和反对的所有这些方法，所以我要寻找从别人多一些指导谁可能已接近之前解决这个问题。

I can see pro's and con's to all these methods so I am looking for some more guidance from someone who may have approached and solved this issue before.

我正在考虑做这两种方法1安培; 2，因此，我可以提供所需的所有功能，但我担心我可能是过于复杂/复制功能。

I am considering doing both methods 1 & 2, thus I can provide all the functionality needed, but I am concerned I may be over-complicating/duplicating functionality.

推荐答案

REST API的必须是超媒体驱动。见的超媒体作为应用程序状态（HATEOAS）的约束的引擎。所以，不要浪费你的URL模式时，因为它们不是RESTful的。 URLPATTERN牵涉一个客户机和一个服务器之间的紧耦合;简单地说，客户端必须知道如何的URL看起来并已构建它们的能力。

REST API must be hypermedia-driven. See Hypermedia as the Engine of Application State (HATEOAS) constraint. So, don't waste your time on URLPatterns, because they are not RESTful. URLPattern implicates tight-coupling between a client and a server; simply, the client must be aware of how URLs look like and has an ability to construct them.

考虑这个REST设计为您的使用情况：

Consider this REST design for your use-case:

文件的重新presentation包含一个链接，客户端可以发表评论，或使用GET的获取有关文件的所有意见。例如。

The representation of a document contains a link where the client can POST comments or with using of GET get all comments on the document. e.g.

{
  ...
  "comments" : {
      "href": ".. url ..",
      "rel": ["create-new-comment", "list-comments"]
  }
}

一个客户端只需要此URL，并执行GET或在URL POST方法;没有知识的网址怎么回事，是什么样子。

A client just takes this URL and performs GET or POST method on the URL; without a knowledge how the URL is, looks like.

也看到这个职位：

http://roy.gbiv.com/解开/ 2008 / REST的API，必须待超文本驱动

这篇关于资源集合之间的REST API设计链接的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！