mapping the api landscape

2014-05-21 @ 15:22#

this week i had the opportunity to deliver a "lightning talk" at the APIStrat Tech Un-Workshop at Gluecon 2014 . the event was focused on two key topics: IoT and Service Description and Discovery. i was in the Service Description/Discovery track and delivered a talk called "Mapping the API Landscape" (slides). i won't cover the entire talk here (the text BTW has lots of links to information i could not discuss on stage this week) but did want to hit some key points.

what Google's self-driving car tells us

the "gCar" has been in the news again and a key point that was disussed at some length in these articles was the fact that the car depends on a very detailed map of the roadways. in fact, the car currently can only drive in the Mountain View, CA area since that is the only landscape that is mapped well enough for the car to navigate.

so, the Google car does not "discover" anything while drivig. it actually recognizes intersections, traffic lights, etc. through a special representation of the landscape that contains all the right annotations. this reliance on a known map allows the car to navigate successfully between two points within that landscape. this is no simple feat, of course. reacting to surroundings "at speed" takes serious computing power and that's one of the things that makes the Google implementation so amazing.

Norman's Action Lifecycle

the process of navigating from A to B is a goal-driven process that we see very often in nature. ants, micro-organisms, etc. all do this. HCI expert, Donald Norman calls this process the Action Lifecycle or Seven Stages of Action .

this is how we learned to write GUI intefaces, too. wait for a keystroke or button-click, process that action, affect the UI, then allow the user to evaluate the changes and decide if another action is needed. we build Web servers like this, too. wait for a request, process it, modify the back-end (if needed) and reflect results back to the requestor. game programming works like this, too. but it's rare to see "Web Clients" written this way. they continue to look like single-minded bots that just "go from A to B" and ignore landmarks; incapable of actually reacting to surroundings.

client apps and web maps

why are most web client apps "one-off" implementations that are likely to break over time? because client dev's don't have decent "maps" of the Web landscape. and good maps are not just "photos" of the surroundings, but heavily annotated representations with recognizable symbols and landmarks. most servers today just belch out JSON or XML with almost no recognizable symbols or signage (e.g. hypermedia controls, etc.).

so what we need to do is create maps for devs to use so that they can build their own client applications and solve their own problems. client apps should be free to follow whatever route within that map that they wish -- not just follow the path that server developers decide upon.

let's make maps!

things like Service Description formats, and discovery protocols are all ways to start creating more maps for client devs to rely upon. using hypermedia in responses provides the symbols and signs client apps can use at runtime (like the Google car) in order to navigate in realtime.

there are several description formats (see my paper Hold your Nose vs. Follow your Nose for more on this). in the book, RESTful Web APIs Leonard Richardson and i list close to 20 options for expressing hypermedia in Web responses. and more have come online since the book was published last year.

we have all we need. we just need to make more maps!