Example: Representing collections

Item collections can be represented as JSON arrays like this:

{
  "items": [
    { ... item 1 ... },
    { ... item 2 ... },
    ...
  ],
  "@controls": 
  { ... }
}

Mason does not impose any restrictions on the API data format and have no abstraction for "embedded" items like for instance HAL does. If you have embedded items then you can simply give them their own "self" link:

{
  "items": [
    {
      "title": "This is item 1",
      "@controls": {
        "self": { "href": "...", "title": "Link to item 1" }
      }
    },
    {
      "title": "This is item 2",
      "@controls": {
        "self": { "href": "...", "title": "Link to item 2" }
      }
    }
  ],
  "@controls": 
  { ... }
}

Wrapping the array in the containing Mason object makes it possible to add other properties to the collection of items, for instance pagination and some developer information:

{
  "@meta": {
    "@description": "This is a collection of items. You can look for 'next' and 'prev' links for pagination."
  }
  "page": 1,
  "items": [
    { ... item 1 ... },
    { ... item 2 ... },
    ...
  ],
  "@controls": 
  {
    "next": { "href": "..." },
    // No "previous" link since its the first page
  }
}

See for instance http://mason-issue-tracker.azurewebsites.net/projects for a live example of a collection of projects in the example issue tracker.