Websites VS. APIs
I’ve been recently pulled into some Twitter conversations about the quality of the new open data portal “launched” by the German government available at govdata.de. I put launched in quotation marks as the launch has been a rather rocky one critized through out the web.
I in particular made fun of the very verbose api resource the portal exposes. If you do a GET on it all you get returned is a:
{ "version" : 1 }
What I was trying to point at - and I think most of my Twitter followers are aware that I am into the field of REST web services a bit - is that it’s absolutely sad that it’s 2013 and we still see “APIs” published to the web that lack any kind of hypermedia elements. My initial tweet caused a bit of response and started some interesting conversation.
Ina Schiefendecker (I assume to be related to the GovData project as she is working for Fraunhofer FOKUS, responsible for implementing the portal) pointed me to the documentation:
Just have a look: http://t.co/cA4Q0pXzKQ or http://t.co/Qd114XnfbG
I replied that adding hypermedia elements to the responses would turn the chunks of data into a usable API, which she responded to with:
If you want hypermedia take the portal, if you want to program take the API
My initial reaction to this was a deep *sigh* and thinking that the team apparently hasn’t understood the value of hypermedia in API design. But taking a step back, this statement contains an interesting aspect:
For the GovData team the website is something different than the API
Why is that the case? If it’s on the web, embrace the web, period. Why would you choose the web as the platform of choice if the first thing you do right after that is starting to ignore it’s core traits? Hypermedia is essential to way the web works, thus so should it be to your web site and APIs you expose to the web.
To me it feels like implementation aspects leaking through at this point. According to some leaked stack traces, the portal is built with JBoss, Liferay and JSF (sigh), the API with CKAN. Totally different technology stacks, but does that impose a real conceptual difference to a web site and a web API?
Playing devil’s advocate a bit one now could ask:
If a web site is the same as an API and you have a website, why do you need something you call “a dedicated API” at all?
The core point here is what makes up “dedicated” in the first place. To stay with REST terms, in my opinion “dedicated” is embodied in the representation design for different client types. Even for well designed websites you usually serve a representation that consists of certain elements that serve the purpose of being displayed to a user through a browser. This is essentially a core principle of REST: you choose a media type tailored for a specific use case to optimize on bandwidth, performance and client (the browser in this case) usability. And so do web APIs, except the driving factors being others: potentially much more focused on limiting bandwidth usage, the numer of requests necessary and ease of extracting data from responses. You also do so when exposing your web site content to feed readers by choosing Atom or RSS. But in the end it’s all about designing representations for clients with different requirements. So here’s what it boils down to:
Both your website and your API benefit from being considered ‘the same thing’ with different representations.
There’s absolutely no point in differentiating between the apparently different things “website” and “web API”, especially when it comes to the aspect of hypermedia: if it’s on the web, embrace the web.
Edit - 2013-04-30: Oliver Wolf has a great presentation on active VS. passive APIs on speakerdeck.com. It uses the issues with GovData (or the CKAN API to be precise) to suggest improvements to the APIs.
