DocJSON – JSON HyperMedia Documents


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 🙂


Related: JSON API →


  "links": {
    "": {
      "href": "{}",
      "type": "people"
    "posts.comments": {
      "href": "{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


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

JSON.stringify()’s arguments

JSON.stringify() has more than one argument:

  1. value – the value one wants to convert to a string
  2. replacer – an array or a function to filter fields
  3. space – the number of spaces (or a string) to use for indentation
var person = {"name":"Jim Cowart","location":{"city":{"name":"Chattanooga","population":167674},"state":{"name":"Tennessee","abbreviation":"TN","population":6403000}},"company":"appendTo"};

JSON.stringify(person, ["name", "company"], 4);
/* produces:
    "name": "Jim Cowart",
    "company": "appendTo"

What You Might Not Know About JSON.stringify() →

(via @LeaVerou)

Simple REST API Explorer

Just pushed a new project to GitHub named Simple REST API Explorer, a simple way to showcasing and exploring all endpoints of your RESTful API.

The demo allows you to call some Twitter API endpoints a sample RESTful API I’ve quickly knocked up as the Twitter API is rather unstructured. Update the index.html file to reflect your own API endpoints. All the rest will go automagically.

Some notes that go with this first version:

  • Only tested with APIs returning JSON or JSONP.
  • Custom headers don’t work with JSONP. If you do need both JSONP and an API-Key: ask your API provider to enable CORS so you can switch to JSON.
  • Only GET supported (for now?) Already fixed 😉

Simple REST API Explorer Demo →
Simple REST API Explorer Source (GitHub) →