Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Collection Link Relation Type

Peter Karman edited this page · 9 revisions
Clone this wiki locally

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.

Something went wrong with that request. Please try again.