I’m Richard Baines, Product Manager for our Application Programming Interface (API) Platform, which allows the secure exchange of data between HMRC and third parties like the tax software packages used by many businesses and agents.
One common misconception about surfacing an API to third party developers is we don’t need to think directly about user needs because they control the user interface for their software with their customers. However software developers are our users, and there’s very little difference in the spirit of how we approach the task of building an API compared to a web based digital service.
Using human-readable HTML
Software developers use our Developer Hub to learn about our APIs. To make sure it’s as easy as possible for developers to learn how to use them the majority of our APIs are represented as human-readable HTML in the JSON format.
We follow the principle from the GDS Service Design Manual that
building a website which exposes data through links and services through HTML forms encourages exploration and leads to discovery through hypertext.
This sentence might sound abstract at first, but it is interesting as it gives a bit of insight as to how we’ve adopted REST in the way we build our APIs. We want software developers to be able to read about our APIs with no prior knowledge, beyond the initial URI we give them and a set of standard media types that would be reasonable to expect they already understand.
It’s a little bit like how you surf the web. When you sit down at your computer, you wouldn’t expect to need a list of URLs on a piece of paper in order to find every website you wish to visit (unless you’re trapped in 1995). Instead, you start with one website address or a bookmark you’ve saved, and progressively click links from one page to the next to find the resources you need.
To make this a reality, we need a few things in place
I’ve been developing a standardised process for API Design across HMRC by working with our architects to develop API principles for our producer teams to follow which encourage reuse and adoption of concepts like HATEOAS. These principles will help us decouple the API documentation from any complexity that might be found in our backend systems, or from changes we make to them. Any breaking changes we make to an API can have a negative impact on our software developers, so to truly put their user needs first we try to minimise breaking changes with good API design.
I’ve also been working with various teams on creating a domain model to represent the entities that interact with HMRC, the duties or taxes that we administer and the parameters we might find in this complex minefield of data. This means the structure of URIs is repeatable and logical for developers to understand.
Working closer with software developers
There’s already a lot of interest from software developers in our RESTful APIs, and lots of great ideas on how they’re intending to build software products. My colleague Lisa Barnett (Product Manager for the Developer Hub) has been working closely with them on a Terms of Use agreement to be published soon. It sets out how we’re going to collaborate with developers, and outlines the standards and principles both HMRC and Software Developers are expected to meet to ensure the security and protection of customer data.
Further Improvements
To make it even easier for developers to innovate, this year we’re looking closely at how we can improve the way API documentation is structured and standardised on the Developer Hub. This means consistency in the taxonomy we use, and separation of the API documentation from the guidance that explains how to build software. We’ll be improving everything from registering on the Developer Hub for the first time, creating a software application, testing an application through to requesting live production credentials.
Some software may only integrate with one API, however some developers may choose to use snippets of data from several APIs. That’s up to them, but if we continue to focus on putting their user needs at the forefront of what we do, we can ensure that making great tax software is easier than ever before.