What is API design?

What is design?

Design is about choice. And making the right ones.

Conventions

RFC 4627

Go read some docs.

Human vs. Machine readable

Option 1: totally custom media type

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