JSON API

{
  "links": {
    "posts.author": {
      "href": "http://example.com/people/{posts.author}",
      "type": "people"
    },
    "posts.comments": {
      "href": "http://example.com/comments/{posts.comments}",
      "type": "comments"
    }
  }
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "1", "2", "3" ]
   }, {
    "id": "2",
    "title": "The Parley Letter",
    "links": {
      "author": "9",
      "comments": [ "4", "5" ]
   }, {
    "id": "1",
    "title": "Dependency Injection is Not a Virtue",
    "links": {
      "author": "9",
      "comments": [ "6" ]
    }
  }],
  "people": [{
    "id": "9",
    "name": "@d2h"
  }],
  "comments": [{
    "id": "1",
    "body": "Mmmmmakase"
  }, {
    "id": "2",
    "body": "I prefer unagi"
  }, {
    "id": "3",
    "body": "What's Omakase?"
  }, {
    "id": "4",
    "body": "Parley is a discussion, especially one between enemies"
  }, {
    "id": "5",
    "body": "The parsley letter"
  }, {
    "id": "6",
    "body": "Dependency Injection is Not a Vice"
  }]
}

“JSON API” is a JSON-based read/write hypermedia-type designed to support a smart client who wishes build a data-store of information.

Good to see this formalised, as JSON on its own is not Hypermedia. Mime-type to be is application/vnd.api+json (pending).

On the other hand I’ve been pondering about tolerating JSON based APIs that return structured JSON (making it “RMM Level 2.5”) as plain JSON (application/json). Take my own Movies DB API for example: it’s all structured and could be RMM Level 3 (and thus be a genuine Hypermedia API) if it wouldn’t be served as application/json, but with a mime-type I’d have to regiser at IANA … but registering one would just loiter the standards space, make it an unwanted option — XKCD nailed the reasoning behind this perfectly

JSON API →

Not sure what a RESTful/Hypermedia API is? Then check out my course materials on the subject: RESTful APIs →

Elsewhere , , , ,

One Response to JSON API

  1. Pingback: DocJSON – JSON HyperMedia Documents | Bram.us

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>