https://insidegovuk.blog.gov.uk/2018/04/04/what-we-learnt-from-creating-api-documentation/

What we learnt from creating API documentation

One of the objectives of our Q2 mission was to create documentation for the GOV.UK content application programming interface (API).

This is a public API that allows machines to access and republish GOV.UK content.

Before we started the project

The GOV.UK content API was technically available to the public and was being used by organisations such as the British Library and the Foreign & Commonwealth Office. However, it wasn’t officially supported for external use and there wasn’t a formal process for users to get in touch if they needed help.

Documentation was somewhat sparse and spread across different places internally. It was also authored towards GOV.UK developers.

Why we’re making it public

Many citizens and professionals find GOV.UK content useful. We want to support the API to make access to that content as easy as possible.

Alongside this, we’ve committed to the Open Governments Partnership to provide APIs for government content as part of the UK Open Government National Action Plan.

This presents a massive opportunity for us to learn from users and evolve the offering of the API.

We’re launching the GOV.UK content API as a beta. This means it may be subject to change and improvement as we learn from its usage and user feedback. It also means that new applications can be built using GOV.UK content API data.

Starting with user needs

As always, we started the project by thinking about user needs. We wanted to make sure we understood the baseline documentation we needed to provide to users of an API and to be consistent with the standard which has been set at GDS.

We found that users need to know:

  • how to use the API
  • how to stay informed about changes to the API
  • how to ask for help

We identified these needs by doing research into existing public APIs at GDS and how they’re documented, bearing in mind that many of these services are in beta and documentation may still be in progress.

In particular, we wanted to understand how the various teams generate their API documentation and whether it conforms to any particular standards. Part of this involved looking at the Service Manual guidance on API documentation.

As advocates of open data we also wanted to embrace the best practices of open standards.

We chose to document the GOV.UK Content API using OpenAPI as this is the proposed open standard for government. We’re piloting using OpenAPI in our documentation and will feed back our learnings to the Open Standards team at GDS.

Learning from our technical writer community

GDS has a dedicated team of tech writers. One of the things they’re working on is providing various level of guidance on producing API documentation.

We spoke with Jen Lambourne to get her views on best practice for documenting APIs. She directed us towards a couple of useful blog posts about developing APIs that are being considered as part of the guidance:

The tech writing team will soon be publishing guidance and providing training on API documentation.

Making use of existing tools

While looking into ways of presenting our API documentation, we found a couple of tools that are already being used at GDS.

One is the GOV.UK tech docs template, which builds technical documentation using a GOV.UK style. Teams such as Government PaaS and GOV.UK Pay are already using this for their documentation.

We also found that the Digital Marketplace team built their documentation by generating markdown from OpenAPI. We decided to adopt this approach.

We’ll also be using a tool called Widdershins to help us generate the markdown.

Reflecting on some things

During our time documenting the GOV.UK content API we came across a few hurdles.

Firstly, we decided to embrace version 3 of OpenAPI, which was recently made public. It’s an improvement on version 2 - but it’s a new release, which means there are limited tools supporting it.

Despite the wider selection of tooling for version 2, we knew that it wasn’t a good long-term choice as we would have been building for a version that would eventually be deprecated.

Another challenge we faced was the fact that some concepts in the GOV.UK content API are complicated to document. For example, we know that some of the terminology we use is internal language and may not necessarily be clear to users outside of GOV.UK.

There are also publishing concepts that will be familiar to our internal publishers, but may not be obvious to other users. We intend to document future iterations concurrently to ease this.

Where we go next

Now that the documentation for the GOV.UK content API is live, we want to learn about users’ experiences of using it so we can improve it.

To help us do this, we’ve implemented Google Analytics to track hits to the API and documentation microsite, and analyse trends. In both cases, the data is anonymised.

Additionally, there’s a feedback section in the documentation for users to share suggestions and improvements with the team.

Finally, we’ve published a blog post to gather expressions of interest in the GOV.UK content API, to help us understand what users might want from future iterations of the API.

Patrick is an Associate Product Manager on the Digital Marketplace. Emma is a Developer on GOV.UK.