Top Ten ways to create a great API

I explained API’s in an earlier post, now, as someone who works with several APIs it’s time to put down my top ten features every API needs. If you’re working on a web 2 application and you haven’t thought about your API yet, then this is for you.

If you still need an analogy think of a railway station designer – you are making platforms for the trains to use. Everyone uses common elements to make it work – railway time, signals, timetable boards, track guage, platform numbers and so on. These are the building blocks of a good API – common standards and terms.

So, my top ten, in reverse order:

10. Provide good libraries and example code – it’s obvious but so often missed. You can’t just write your API and stop there – do the developer’s work for them and provide a class library and example app. Nothing gets us coding and using your API faster.

9. Fast Perfromance – no-one likes a slow coach, this is as true for platforms as for applications. If our application is fast we don’t want your platform to slow us down.

8. Use jargon – Jargon exists for a reason – to make sure we are all talking about the same thing. I’d rather learn new jargon FQL, FBML (et al.) than have to continually deal with long winded explanations of how the new technology differs from an old one.

7. Use jargon consistently – if a view is a list in your world keep using the word view for a list, don’t suddenly flick and use the word view for a viewing window. One word = one job.

6. Reduce the features- keep it simple, just have one way to do things. The more options there are to an API the harder it is to learn.

5. Version your platform – I know this is a contentious subject but versions really do help – even if you take the Microsoft approach of 16 digit version numbers. If you’re doing nightly builds then make this visible – there’s nothing more frustrating than seeing your app work one day and fail the next and you don’t know whether it’s your own slack code or that the platform has moved underneath you.

4. Add a Sandbox – Paypal’s developer Sandbox is absolutely wonderful, Facebook have some API and FQL tools that work. Give us ways to test our apps properly.

3. Support a developer forum – we learn best from others who have been there. Most API issues I solve by seeing how others who hit the same stumbling block did it – don’t forget to add a really good search engine.

2. Be a responsive tech team – if you put up a post on the forum or a bug in the tracker – you want a response asap. By the time a software project has got to the actual developers every day counts, this is the coal face and time waiting for the API team to get back is a real bind. Sometimes you can’t progress your code without their response.

1. Believe in Up-to-date documentation – if your documentation falls behind your API forget it, the worst phrase I see from API developers is “implemented but not documented” – well what use is that? Put in place a Wiki and get your developers to make updates if needed.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: