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
— Richard Marr (@richmarr) August 23, 2012
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.
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.
@jockbu Consistency, separation of concerns, idempotence, a clear transactional/billing model, don’t make me think and work globally
— Lex Mitchell (@LexMitchell) August 23, 2012
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.
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
@jockbu Making it simple to draw data without making assumptions about what people will want to do with that data. Let your users crunch it.
— Manley (@LordManley) August 23, 2012
@jockbu Indeed – by all means provide common outputs, but keep the raw data available (or at least, any you do not mind sharing).
— Manley (@LordManley) August 23, 2012
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.
@jockbu simplicity (hence REST, state is complexity), reliability, familiarity, clear and reasonable rules of the road, and docs, docs, docs
— Andrew Walkingshaw (@covert) August 23, 2012
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.
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.
- 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.