A JSON API
to bind them all

Common web frameworks

• Good at simple CRUD interfaces
• Pretty bad at supporting RESTful APIs

REST... Hypermedia

• HTML, anchor tags!
• XML, link tags with rel and href attributes?
• JSON ?!

JSON API

• A community-driven standard for RESTful JSON APIs
• ID-based, easier to start with
• URL-based, more resilient to changes
• Early development stage but very active

(Partial) Implementations

• Ember Data
• Active Model Serializers

JSON with reserved keys

meta, links, href, type, id

A media type (IANA registration pending)

application/vnd.api+json

Tailored with profile link header: rfc6906

HTTP/1.1 200 OK

Content-Type: application/vnd.api+json

Link: <http://example.com/profile>;
      rel="profile"

• Similar to HTML microformats
• Avoid proliferation of media types
• Allow self-descriptive messages

An API for Riviera.rb

GET http://rivierarb.fr/api

Accept: application/vnd.api+json

HTTP/1.1 200 OK

Content-Type: application/vnd.api+json

Link: <http://rivierarb.fr/api/profile>;
      rel="profile"

{
  "api": [{
    "links": {
      "posts": "http://rivierarb.fr/api/posts",
      "people": "http://rivierarb.fr/api/people"
    }
  }]
}

GET http://rivierarb.fr/api/posts

{
  "posts": [{
    "id": "1",
    "title": "A JSON API to bind them all",
    "href": "http://rivierarb.fr/api/posts/1"
  }]
}

Relationships

{
  "posts": [{
    "id": "1",
    "title": "A JSON API to bind them all",
    "links": {
      "comments":
        "http://rivierarb.fr/api/posts/1/comments"
    }
  }]
}

URI Templates: rfc6570

{
  "links": {
    "posts.author":
      "http://rivierarb.fr/api/people/{posts.author}"
  },
  "posts": [{
    "id": "1",
    "title": "A JSON API to bind them all",
    "links": { "author": "6" }
  }, {
    "id": "2",
    "title": "RuLu 2013, June 20-21, Lyon",
    "links": { "author": "9" }
  }]
}

Compounds

{
  "links": {
    "posts.author": {
      "href": "http://.../people/{posts.author}",
      "type": "people"
    }
  },
  "posts": [{
    "id": "1",
    "title": "A JSON API to bind them all",
    "links": { "author": "6" }
  }],
  "people": [{"id": "6", "name": "rivierarb"}]
}

References

• jsonapi.org
• The 'profile' Link Relation and You
• rfc6906: The 'profile' Link Relation Type
• rfc6570: URI Template
• Ember Data
• Active Model Serializers