Tag Archives: json

A DocJSON document consists of standard JSON with the addition of a set of hypermedia controls that are used to express the actions that may be taken. DocJSON is a flexible document format that does not impose any structural restrictions either on the data representation style or on the layout of hypermedia controls used within the document.

The true power of the spec lies in restrictions it oposes:

A document may be any valid JSON with the single restriction that the object key "_type" is reserved.

Real genius imho, as it allows the implementer to use any specific structure he wants instead of imposing a structure as other formats such as Collection+JSON, Siren, Hal, JSON-LD, etc. do.

If for one always inject the returned HTTP status code as a status object into the response (example). With DocJSON I’m allowed to do so, plus I can make my API discoverable by consumers who have no prior knowledge of the keys it holds.

Linking back to some HyperMedia things I’ve been tinkering about myself this might actually formulate the answer to the problem I had: wanting to roll my own structure without needing to register a new format (which one shouldn’t).

Looking forward to how this spec will evolve 🙂

DocJSON →

{
  "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 →