When I was a young lad growing up in Hounslow, I remember saying “Mum, do you think I may one day be part of building an API platform?” She said, “Son, you can do anything you like”.

What disappoints me about her, though, was that she didn’t give me the Five Golden Rules to Building Great APIs, there and then.

Equal Experts has been an integral part of building a 21st century digital platform at HMRC for the last 3 years (which you can read more about in Duncan Crawford’s piece on Unlocking potential in the public sector). But for the last year, we’ve also been driving the HMRC Digital platform to a new level by creating an API platform.

In fact, with 75% of all tax submissions done via 3rd party software, the API platform is arguably the most important delivery of the HMRC Digital platform. So we’d better get it right.

I’ve been closely involved in this work, and now here are my 5 Golden Rules of Building APIs. I hope my mum is reading this article!

1) Have a vision

“We knew that designing APIs was a very important task as we’d only have one chance to get it right.” – 10 lessons from 10 years of AWS

Set your vision before you start building your APIs. The quote above is from an AWS article celebrating 10 years of AWS, and it is so right. You won’t get an opportunity to change your strategy or your platform without massive overhaul and pain to your clients. Having that vision from the start will guide you in all your decisions, from which tools to use, what architect to put in place, what style you want… And from there, you’ll dramatically reduce the risk of needing a major overhaul.

2) Make it beautiful

“We don’t get a chance to do too many things, and every one should be really excellent” – Steve Jobs

As self indulgent as it may seem to call your APIs beautiful, that is exactly what they ought to be. APIs are the public face of your IT, and as such are part of your brand and reputation – and an insight into your quality. You wouldn’t deliver an ugly website, so don’t deliver an ugly API. What is beautiful? Rules 3 and 4 can help you get there…

3) Change your perspective

Focus on the domain, not business process.

I started my adventure in software development back in 1999, working for British Airways (I was very young when I started work). The web strategy back then was to move our offline business processes online. It seemed sensible at the time, when we were all new to the digital world, but it was a flawed approach. Those business processes were not created for the digital world – they were created for cryptic commands into mainframe terminals, paper forms and intelligent (human) intervention.

Process is an implementation detail; it’s your domain, and not your processes, that should guide how you provide your APIs. For example, rather than having a tax calculator API, you would provide a full tax API, with tax calculation just being a part of it. This will lead you to a much more elegant solution.

4) Use Hypermedia

“If the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.” – Roy Fielding

The REST architectural style is the perfect approach to delivering APIs – if you don’t do REST, you’re not getting the good stuff. It ensures loose coupling by hiding implementation, improves performance and reduces load on the server. It also takes control of business logic away from your clients, which actually allows them more freedom to innovate.

For example, rather than having to spend six months on coding new tax regulations and rules, how’s about using the time to monitor income and spending habits, and then provide ways to automatically create a business budget? Or create software that can link up with train, plane or tax systems to automatically track travel expenditure? Your end users will love you for it (even if they won’t realise it!).

To do this, you need hypermedia controls. They are a central tenet of REST, so if you don’t use them, you aren’t really doing REST at all.

5) You ARE ready

Your organisation is mature enough to start building beautiful APIs, right now.

It’s easy for people to complain that their organisation is not ready or sufficiently mature to deliver the kind of platform that people will envy. But it simply isn’t true. The maturity of an organisation simply describes where it is now, not where it wants to be (or where it can be). After all, you’re building a brand new platform – APIs can play a major role in getting you where you want to be.

As for the organisation we’re working with – HMRC – the API platform is currently in Beta. We very much look forward to the time when we can publish the platform to the wider world and showcase the great things HMRC will be able to do for its customers; look out for another update when that happens.