The 8 traits of a successful web API

The 8 traits of a successful web API

I’ve been talking to web developers, engineers and product people about APIs.  After all, they’re the ones using them.  From our discussions, it’s clear that the best web APIs share some common traits.  Would you like to know what’s going to make yours more successful?

If you’re not familiar with what a web API is – go and find out!  You’re going come across them pretty often in your product management career.  Simply put, they allow software, websites and apps to exchange information or fulfil a particular task.  Think of them as building blocks for a more complex piece of software.

Over the years, the technologies used for APIs may have changed, but their purpose hasn’t.  Today, APIs, particularly web-based ones, have proliferated – if you need a specific capability, there is a good chance that someone has already written and published a web API that does exactly what you need, saving you the bother.  And this is a fine thing indeed.

With all these web APIs kicking around, it’s inevitable that some overlap with each other in function. When this happened, developers often voted with their feet.  What was it that set the winner apart?

I sampled the views of web developers on what they thought made a good web API.  Here’s what they came back with:

1. Useful and easy to use #

Just like any other product, you need to ensure your API is solving a problem that people actually have.  Aim to make your API as easy to use as possible by building in the following characteristics.

2. Reliable #

Ensure that your API can be relied on.  If you’re asking developers to use your API as a building block for their app, they’re not going to favour a flaky API.

3. Consistent #

Quirky behaviour in a person can sometimes be excused as “character”.  An eccentric API, however, is not particularly desirable.  Wherever possible, be consistent in the way similar tasks are carried out, both in terms of what is fed in and what is given back.

Another angle on this is consistency with your brand values.  If you’re pitching your API as being easier to use, or quicker to develop with than other choices out there, make sure this reflects the reality of the user experience.

4. Fast #

If your API is meant to return a response immediately, do so as quickly as possible.  Developers won’t be keen to slow down their app because your API takes its own sweet time to do things.

5. Structured but raw data #

When returning data, structure it appropriately so it can be easily consumed and manipulated.  Preserve access to the raw information.  As soon as you start to manipulate it pre-emptively, you’re making assumptions about how people will use your API and these may constrain its use.

6. Simple #

Keep things simple – in lots of different ways: avoid the whole area of maintaining state by being truly RESTful; have a straightforward authentication method; make usage reporting and billing transparent and uncomplicated.

7. Familiar #

There’s a time and a place to ditch convention and innovate wildly, say, when you’ve found a better, easier way to do something.  However, if you’re doing it solely to be obtuse and stand out from the competition, you run the risk of alienating developers who expect those conventions to be followed.

8. Documentation and support #

Last, but not least, is how you document your API.  Understand how people need to use your documentation: are they looking for a conceptual overview of the whole thing, or simply the parameters to a specific function call?  Chances are you will need to provide both, and they are often quite separate.  Evernote is well-regarded for its API documentation’s ease of use.  Note the stark difference between their conceptual overview and their API reference docs.

Provide working examples to illustrate your methods and keep your docs accessible, don’t lock them away in a PDF or behind a members-only login.  You can also benefit from increased visitors to your website if you make your docs friendly to search engines.

Finally, support your users.  Engaging with them on social media or in a support forum can yield valuable insight into how people are using your API, and where it can be improved.

Further reading #

Great API Documentation Seen As Key To API Success – ProgrammableWeb

I’m very grateful to Richard Marr (@richmarr), Lex Mitchell (@LexMitchell), Manley (@LordManley), Andrew Walkingshaw (@covert), Luke Pryor (@lukosan) and Sam Collins (@smcllns) for sharing their views with me.

Note that in the intervening years since original publication of this article, some of the respondents have taken their Twitter accounts private.


Get articles when they’re published

My articles get published irregularly (erratically, some might say). Never miss an article again by getting them delivered direct to your inbox as soon as they go live.  


Read more from Jock

The Practitioner's Guide to Product Management book cover

The Practitioner's Guide To Product Management

by Jock Busuttil

“This is a great book for Product Managers or those considering a career in Product Management.”

— Lyndsay Denton

Jock Busuttil is a freelance head of product, product management coach and author. He has spent over two decades working with technology companies to improve their product management practices, from startups to multinationals. In 2012 Jock founded Product People Limited, which provides product management consultancy, coaching and training. Its clients include BBC, University of Cambridge, Ometria, Prolific and the UK’s Ministry of Justice and Government Digital Service (GDS). Jock holds a master’s degree in Classics from the University of Cambridge. He is the author of the popular book The Practitioner’s Guide To Product Management, which was published in January 2015 by Grand Central Publishing in the US and Piatkus in the UK. He writes the blog I Manage Products and weekly product management newsletter PRODUCTHEAD. You can find him on Mastodon, Twitter and LinkedIn.

Agree? Disagree? Share your views: