REST API设计链接资源集合

Question

我一直在思考定义具有相互依赖性的资源集合的正确方法.

例如,让我们考虑可以通过URI独立访问的"文档"和"注释":

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

但是,我们通常希望收集与特定文档相关的注释.这就产生了一个围绕如何进行检验的设计问题.

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

1.)在文档uri之后提供一个集合uri以供评论

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

2.)为评论集合提供参数以按文档选择

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

3.)使用内容协商来请求通过Accept标头返回相关的注释.

// 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.

方法2提供了许多与#1相同的好处,但是在没有文档上下文的情况下创建注释是没有意义的.由于注释必须明确与文档相关.

方法3从GET和POST/create角度来看很有趣,但是通过更新和删除会变得有点毛茸茸.

我可以看到所有这些方法的专家和骗子,所以我正在寻找一些可能已经接近并解决过这个问题的人的更多指导.

我正在考虑同时使用方法1和2,因此我可以提供所需的所有功能,但我担心我可能会过度复杂/重复功能.

Answer 1

REST API 必须是超媒体驱动的.请参阅超媒体作为应用程序状态引擎(HATEOAS)约束.所以,不要在URLPatterns上浪费你的时间,因为它们不是RESTful.URLPattern暗示客户端和服务器之间的紧密耦合; 简单地说,客户端必须知道URL的外观并且能够构建它们.

根据您的用例考虑这个REST设计:

文档的表示包含客户端可以POST注释或使用GET获取文档的所有注释的链接.例如

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

客户端只需获取此URL并对URL执行GET或POST方法; 不知道URL是怎样的,看起来像.

另见这篇文章:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven