Start small. Stay flexible. That’s the mantra coming out of recent smart city initiatives in Pittsburgh and Boston. To which we…
Blurring the line between API and user interface
APIs are instrumental in OpenDataSoft’s vision and value proposition. While we just put the final touch in the integration of the API within our user interface (and vice versa), it looks like the perfect time to look back and see the path we walked, and how we brought our API within the front-end and made it a first-class citizen together with our other visualizations.
A timeline of Explore’s re-API-fication
Our great adventure started with the version 1 of our API (still running and kicking), and Explore V2 (which was the first version available for our customers). At that time, Explore was a pretty standard Web application, with everything being server-side and a bit of JS to make things look smooth. While being very stable and robust, it lacked a lot in the user experience department, since every trivial action (such as displaying the next 50 results) triggered a page reload; this made the “exploration” experience very rigid, and therefore not very explorative; you’d want to click everywhere like any decent explorer (refine the displayed data, switch between visualizations) but it wouldn’t follow your lead.
In the beginning of 2013, we started a total redesign and rewrite of the front-end. A few rules are imposed : all our interfaces will be based on our APIs (you can’t cheat by going server-side!), with a focus on user “comfort” and usability. The goal was to, once and for all, destroy the sentence “data is not sexy”. A few pillars of this reconstruction were AngularJS and the symbiotic OpenStreetMap + Leaflet, but that’s a story for another time.
In April 2013, we finally deployed the result of this long, fascinating, burger-consuming work. The back-office was entirely rewritten and redesigned, but most of all, the Explore interface, now in V3, became a JS application in which the user can really “play” with data and freely and painlessly switch between filters and visualizations. The change in user experience was quite extreme, even more than we expected, especially due to the immediate feedback of every interaction (the latency depending entirely on the API response time). And the best thing : we finally relied entirely on our API, the same API that our customers build applications with.
By making Explore a pure application of our API, we have gained a few major benefits :
- We are now users of our own API, which allows us to taste the bliss of dogfooding like any startup proud of its product; thus allowing us to directly experience the occasional lacks and pitfalls of our own API, and make it evolve accordingly.
- Explore is now the best demo and live documentation of the API : we just need to pop the Network tab of the browser, and show the API calls after each click.
- By detaching the visualization from the server to put it entirely client-side, and by feeding it with our API, we opened up a lot of possibilities in the future in terms of reuse.
The API as a feature of an Open Data portal
Lately, we wanted to make the API more visible within the Explore interface, using a dedicated tab in each dataset. There were two reasons for that : first, to allow our customers to “showcase” the API in action, acting as a hands-on session for developers, and a gateway for the full documentation; and second, to promote the API in the user interface and show it is really a first-class citizen and not an afterthought, which is important for several of our customers that have an API-centric approach and want to build and maintain an application ecosystem.
The API Console
A developer is a fragile creature, with big and soft eyes. You don’t want to break a developer by making him discover an API using a command-line or typing very very long URLs in a narrow browser bar. When writing Explore V3, we also rewrote our API Console, and it just got a whole bunch of improvements from Florent, our prolific intern :
- The console’s URL is always synchronized with its state (selected service, parameters), so that you can share it to someone at any time by just sending the current URL
- The JSON preview of results is much faster and much more easy to manipulate (object folding; ability to select and copy parts or all of the JSON as valid JSON, even the folded code)
- By adding “console/” after “api/” in an API URL, you’ll end up in a pre-filled console for this API call : API / API Console