Collection Link Relation Type

Peter Karman edited this page Jan 16, 2014 · 9 revisions

The "collection" Link relation can be used to establish "part/whole" relationships. Presence of a "collection" link relation indicates that the current resource belongs to another resource that can be viewed as a collection of other resources. Part/whole relationship is a more generic version of the common "parent/child" relation, therefore "collection" can be used to represent such relationships. Links using the "collection" link relation MUST point to e dereferenceable resource that SHOULD provide a resource of a known media type. Collection link relation MAY point to multiple links.

For example, Collection.doc+JSON media type would represent collection relationship as:

{
  "version" : "1.0"
, "attributes" : {  
    "guid"        : "f84e9018-5c21-4b32-93f8-d519308620f0"
  , "title"       : "Peers Find Less Pressure Borrowing From Each Other"
  , "published"   : "2013-05-10T15:17:00.598Z"
  , "valid"       : { "from" : "2013-05-10T15:17:00.598Z"
                    , "to"   : "2213-05-10T15:17:00.598Z"}
  , "byline"      : "by WENDY KAUFMAN"
  , "hreflang"    : "en" 
  , "description" : ""
  , "contentencoded": "..."
  , "contenttemplated": "..."
  }
, "items" : [ARRAY] 
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/story"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ { "href" : "http://api.pmp.io/docs/f84e9018-5c21-4b32-93f8-d519308620f0"}]
  , "collection"   : [ { "href" : "http://api.pmp.io/docs/5676eebf-0261-4de9-95e4-762f9b8d5039"}
                     , { "href" : "http://api.pmp.io/docs/eb3904f2-ddfd-4dcf-8614-c989dcec88ab"}]
  , "queries"      : [ ... ]
  , "edit-form"    : [ ... ]
  }  
, "error" : {OBJECT}
}

Please notice the links.collection relationship in the example above. It points to two URLs. The expectation is that each URL returns a document describing the corresponding collection. For instance, dereferencing URL http://api.pmp.io/docs/5676eebf-0261-4de9-95e4-762f9b8d5039 could return a document such as:

{
  "version" : "1.0"
, "attributes" : {  
    "guid"        : "8e2cf9d8-7b9b-4369-9032-4c1819df8f2a"
  , "title"       : "All Things Considered Rundown for Jan 10th, 2013"
  , "hosts"       : []
  , "valid"       : { "from" : "2013-01-10T15:17:00.598Z"
                    , "to"   : "2213-01-10T15:17:00.598Z"}
  }
, "items" : [ ... ] 
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/rundown"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ {"href" : "http://api.pmp.io/docs/8e2cf9d8-7b9b-4369-9032-4c1819df8f2a"}]
  , "collection"   : [ {"href" : "4aa65654-8180-42b5-98b0-b7b252dd2267"}]
  , "queries"      : [ ... ]
  , "edit-form"    : [ ... ]
  }  
, "error" : {OBJECT}
}

Which would establish that the original story is part of a Radio show's (All Things Considered, in this case) rundown. You may also notice that the specific day's rundown points to another collection. It may be that the link points to a document representing the show: All Things Considered. A specific day's rundown does indeed belong to the show, if we wanted to capture such relationship.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.