question about representing collections

23 views
Skip to first unread message

Peter Whitfield

unread,
Feb 18, 2014, 6:24:47 PM2/18/14
to mason-me...@googlegroups.com
I'm trying to mock up an API using Mason as a basis and I'm just trying to understand how I represent a collection of items:

take the endpoint /items

I was hoping to return a json array of item resources but I'm not sure how to do it with mason. I was previously playing with vnd.api+json which simply returned an array regardless of the number of resources referenced, but it doesn't seem like this is how I should do it in mason.

Am I right in saying that I should use the HAL approach of including an "_embedded" element as an array of embedded item resources?

Thanks!

Pete

Jørn Wildt

unread,
Feb 19, 2014, 2:41:44 AM2/19/14
to mason-me...@googlegroups.com
A Mason document has to be an object in order to include @links and other properties. So to return an array you have to wrap it in an object:

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

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",
      "@links": {
        "self": { "href": "...", title: "Link to item 1" }
      }
    },
    {
      "title": "This is item 2",
      "@links": {
        "self": { "href": "...", title: "Link to item 2" }
      }
    }
  ],
  "@links": 
  { ... }
}

Wrapping the array in an object allows you 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 ... },
    ...
  ],
  "@links": 
  {
    "next": { href: "..." },
    // No "previous" link since its the first page
  }
}

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

Regards, Jørn




--
You received this message because you are subscribed to the Google Groups "Mason media type" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mason-media-ty...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

Peter Whitfield

unread,
Feb 19, 2014, 5:09:30 PM2/19/14
to mason-me...@googlegroups.com
Awesome, thanks!

Jørn Wildt

unread,
Feb 20, 2014, 2:14:24 AM2/20/14
to mason-me...@googlegroups.com
Reply all
Reply to author
Forward
0 new messages