Some of the stuff I saw and listen to in Detroit made a few pieces of puzzle click together in my brain. First there was Z who reminded me that we still don't have any good description language for documenting resource oriented hypermedia APIs. I've heard that before and been wondering how it would look like.
Then I talked with Sergey and Dmitri who showed me the resource diagram for their API - this one reminded me so much of UML diagrams that I think we should look into that for inspiration.
I was also at the "Documenting APIs" session where I suddenly found myself talking about our own API documentation - which is written in Word (and that's okay, kind'a). It made me realize that, at its core, such a documentation consists of resource descriptions, link relation descriptions, action descriptions and of course some kind of overview, introduction and tutorial sections.
Someone asked us to explain what a hypermedia API is in one sentence. I came up with "That is an API which can be documented without writing one single absolute URL or relative URL path". I don't exactly think that will catch on, especially not outside this community, but I do believe it is true - if you need to explain URL structures then you are missing something. Unfortunately that one sentence doesn't tell you how to actually implement such an API and as such it is really not very useful.
[I'm pretty sure there is a good Yoda quote to put in here ... like, you now ... "The links with you very strong are here, Luke". Anyone got a better one?]
Dave introduced me to his JSON based description language for APIs and it made me realize that you can do awesome things even in a dead simple format like JSON. Why having to state <twice>everything</twice> when you can do { "single": "everything" }.
Then there were people talking about resources and state machines (thanks again Z). Personally I don't believe much in that analogy - it kind of confuses the graph of resource relationships with the graph of a way-too-simple-never-to-be-found-in-real-life state machine. Z did try to convince me about this but never succeeded - maybe because I am highly colored by my PhD thesis on automatic verification of obnoxiously great state machines :-)
We also got a great deal around API explorers/browsers of various kinds. It seems like every media type have such one now a days - and it makes great sense to me. I truly believe in the power it has when it comes to learning a new API. Thanks to Kristopher Kleva for his story about links, actions and the Sirene browser (you really should blog about that experience!).
I also met Pete Gamache who is the guy behind HyperResource - unfortunately we never really spoke together. He's hypermedia client for Ruby is an interesting solution for interacting with hypermedia APIs in code. Its not exactly new as the same kind of ideas exists in the older tool Restfulie (for Ruby) and my own Ramone library (for C#) - but none the less it shows that there are something worth pursuing here.
All the talks about tooling, SDKs and object models for API resources made me want to work a bit on Ramone and Mason again. It could be cool to make a C# hypermedia resource representation that would allow the client developer to follow links and execute actions in an easy and intuitive way - while at the same time be able to hide some of the stuff that complicates client code in order to make it long lasting and handle (some types of) API changes.
So, thanks to all of you - also those of you that I have forgotten to mention here and of course the people at Apigee that made all of this possible!
