Notes from Camille Baldock, Telling Stories with APIs, 1 October 2014
Kindle API is based on book – book, chapters, pages (nested resources)
“What is the user need?”
User need 1: child reading cares about events and characters
This isn’t linear – it’s linked data rather than a list of resources.
Could use JSON API or HAL (latter has JSON and XML versions)
“HAL embeds child documents recursively”
“JSON API flattens the entire graph of objects at the top level”
HAL uses links to identify things, JSON API uses IDs so caching easier because can identify if already have it.
User need 2: adult reading wants to understand context
e.g. information about the author’s life
DBPedia – linked data version of Wikipedia
JSON-LD [<- LD stands for linked data] = W3C recommended format
– Adds ID and context allowing you to link data
– Means can keep RESTful API and still have semantic web i.e. “Augment existing APIs without introducing breaking changes”
User need 3: deeper understanding of life
“What not to do”:
– Trust Rails to generate JSON
– Think “has many of” is sufficient info about context
“Adding operations to JSON-LD with HYDRA” (can add control e.g. read-only for certain users)
Users don’t think in terms of getting collections. So filtering by certain user group (adult, child) -> different possibilities from the API.
In The Little Prince, Saint-Exupéry makes three attempts at drawing a sheep for the Prince, Prince isn’t happy until he draws a picture of a box that he says has a sheep inside. -> don’t “recreate the wheel” – use standards [= the box] and provide info e.g. the grass for your sheep is over there.
Give real-world examples in your documentation, not list of operations. Swagger’s good.