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

 

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.

Related posts:

This entry was posted in Research and tagged , , , , , by Jock Busuttil. Bookmark the permalink.

About Jock Busuttil

Jock is a product management consultant, author and startup mentor with over thirteen years' experience working in technology. He is the founder of Product People Limited (productpeo.pl), author of imanageproducts.co.uk and has a book coming out in January 2015 to be published by Little, Brown / Piatkus in the UK and Hachette / Grand Central in the US.

One thought on “The 8 traits of a successful web API

  1. Pingback: 29 Oct 2012 | Flagon's Den

Agree? Disagree? Join the conversation: