All of the editorial content on GOV.UK is available in full via an API. It's the same API we use to communicate between the editorial tools and the apps that produce the pages you see.
As I said several months ago, APIs are the bedrock on which GOV.UK is built. Martha Lane Fox's report made delivering high quality APIs a key objective of our work on GOV.UK. Building on APIs and with APIs in mind has been a key architectural principle in the design of our software.
Those who read the previous post will have seen some buttons we were then using to advertise the existence of our APIs. As we worked through the design in more detail and came back to our design rules we realised that for the vast majority of visitors to the site they were a distraction from the quick answer to their need that we'd promised. So the buttons have gone. The links haven't entirely disappeared, and some would argue that their new home is where they should have been all along: in the HTML header alongside all the other 'metadata' associated with the pages.
Where we've built custom tools we've tried to make sure they provide useful content via APIs too. So for our 'planner' tools (maternity/paternity leave) the data can be exported as iCal or JSON. And if you take a close look at the URLs you'll be able to work out how to get it for any date. Similarly all our 'calendar' data (eg. bank holidays) is available in iCal and JSON formats.
We think that's a pretty good start, and we're using those APIs ourselves to put the site together and to test it. What we're not quite ready to promise is that this is the final form for these APIs. We've put together a quick "API explorer" (following the example of Flickr, the Guardian and others) at govuk-api.heroku.com.
It's been really exciting to see a few people playing with the APIs already: Harry Metcalfe used it to explore word frequency on the site, Luke Vincent built his own search interface to the site, and Saul Cozens has built a WordPress plugin to embed GOV.UK content in your blog.
As with everything we've made, our APIs are subject to iteration and very much in beta. We're conscious that right now they're a reasonable way to get at the content, but we need to pay particular attention to how they work with tools like smart answers.
Given that the site is still in beta, the API’s will most likely change which could impact on developers who are building apps on top of them. As the beta evolves we will add versioning to get around this problem. We will also define support levels for our APIs as we move to a more solid footing. Based on the user feedback we get on APIs, we will look at creating curated packages in a future release.
And again as with everything we've made, we're looking for as much feedback as we can get. If you're so inclined, we'd love it if you explored the APIs a bit, let us know how you find them and what we can do to make them more useful for you. If you email us about something you've built we'll also do our best to let you know as the APIs evolve so your code doesn't break! We may even buy you a drink...
James Stewart is a Technical Architect at GDS. You can follow @jystewart on Twitter
9 comments
Comment by New GOV.UK website | Irene's blog posted on
[...] is an Open Source product, therefore an API is provided. The API is also in beta, so its likely to change. Later on, the attendees were given [...]
Comment by Local services and GOV.UK | Government Digital Service posted on
[...] We’d also be interested to hear ideas for how this data could be used once we are able to expose it through our API. [...]
Comment by Russell Garner (@rgarner) posted on
You mention versioning and API evolution - please, please, if you're able, do it like http://developer.github.com/v3/mime/ . You might even (using a "Comment Body Properties"-style approach) render GovSpeak to HTML or plaintext as requested (thereby rendering moot the need for GovSpeak ports in every language?). People requesting simple application/json (including those just using .json in the URL) just get the latest version. Anyone who cares about stability is forced to use an Accept: header and hence manage the evolution from the consuming side, but URLs don't change.
Comment by James Stewart posted on
Thanks for the links, Russ. That all sounds good and I may well come back to you for comments as we figure it out.
Switching the API to return HTML is definitely high on the to do list. I must confess I'd forgotten that we were returning markdown until I put the API Explorer together!
Comment by James Stewart posted on
In a rush to get this post published I neglected to mention another project using the GOV.UK API, Craig Webster's govuk-data: https://github.com/craigw/govuk-data
Craig's put all the site's content into a github repository to provide a way for people to suggest changes to it in just the same way as people can contribute code. If kept up to date, it'd also provide an easy way to see how the content evolves over time.
Comment by Simon Dickson posted on
Without wishing to be too pedantic... there's a lot more potential in Saul Cozens's plugin than simply embedding content 'in your blog'. And it's not just for embedding content, either: it also handles interactive content, such as your 'smart answer' forms.
With five Cabinet-level Whitehall departments using WordPress for their main corporate web presences, we should be well beyond the point of dismissing WordPress-based sites as mere blogs.
And this also opens up the entire gov.uk project to local government, few of whom have the in-house skills to run your open-sourced ruby code, or the necessary cash to hire those skills in.
Comment by James Stewart posted on
Very true! Really looking forward to seeing what those departments and other bodies build with/on the API, and to hearing how we could make it more useful for them.
Comment by KevinJump (@KevinJump) posted on
We all love API's - are you considering any standards for the provision of the APIs ? we've (in Liverpool) been looking at Open311 [www.open311.org] which is well used in the states, and increasingly over here by local authorities.
While there will no doubt be enough interest in gov.uk for an API to get developer buy in - there could be real benefits if central and local government take up the same APIs so people don't have to rework to get information from different sources
Also are there any developments / talks around using apis from local authorities so gov.uk could plug directly into local goverment reporting services ? again Open311 is a standard already in use by places like barnet and southhampton.
Comment by James Stewart posted on
We're looking at Open311 and other standards at the moment. For the information we're currently exposing it doesn't feel like a perfect match but we're going to keep using and will try to adopt existing standards wherever practical.
If you've got specific examples of how you'd like to see us making use of Open311 please do send them this way.