JSON API

A gentle introduction

@steveklabnik

What is API design?

What is design?

Design is about choice. And making the right ones.

-> GET /
<- 200 OK

200 OK

        3foo3bar6baz_id11;2no3yes;

200 OK

        [{"foo":"bar", "baz_id":11},{"no":"yes"}]

Conventions

Content-Type: application/json

https://www.iana.org/assignments/media-types/text/html

RFC 4627

GET /

        Host: mycompany.com

        

        200 OK

        Content-Type: application/json

Go read some docs.

Human vs. Machine readable

Option 1: totally custom media type

application/vnd.mycompany+json

Two components: structure and semantics

Structure: media type

Semantics: profile

Structure: shared

Semantics: specific

JSON suffers from being too generic.

JSON API


{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase"
  }]
}


{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "5", "12", "17", "20" ]
    }
  }]
}


{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "http://example.com/people/1",
      "comments": "http://example.com/comments/5,12,17,20"
    }
  }]
}

Pulling up more common stuff into the generic layer.

Gains:

Better communication with developers
Generic tools
Less details to design (and possibly get wrong)

Thanks!

@steveklabnik / steve@steveklabnik.com