Bulletproof API Design - Part 1

api design, apis

Back in the day when APIs were limited to hardcore desktop application programmers and CSS seemed revolutionary, nobody minded if one API functioned differently from another. It was commonplace to see APIs with totally different, weird, esoteric interfaces, for one simple reason: there just weren’t that many.

It annoyed people, sure. People complained occasionally, sure. But in the grand scheme of things, what did it matter if some annoying GUI programmer had to re-learn the next version of the Windows Forms API? After all, they’re only GUI programmers.

But then APIs became more important. APIs started exposing data, actual, useful data. They started to let developers do actual, important things. Public things. We started to see the age of Web 2.0, of mashups, of applications that didn’t reinvent the wheel every time they had to do something someone else had already done, of the web moving to the desktop and mobile connectivity becoming really prominent and useful. We started to see the real internet.

Here be dragons

Herein lies the problem. With so many APIs popping up at an alarming rate, and no set standards to define them, we’re stuck with loads of different types of API and data serialisation (which is a whole other matter).

As well as enough different APIs to literally drown a cat, documentation is completely variable; it’s a hit-and-run scenario where programmer happiness is left to chance. If you clamber past the barricade of inconsistent interfaces, hideous responses and barely coherent structures, you’re lucky if you can understand what to do with the damn thing. Now that doesn’t sound very good, does it?

Okay, it’s not as bad as I make it out to be; there are some very good APIs out there. But, the fact remains that a lot of developers just don’t put that much attention into the design of their API. All the successful websites that are powered by APIs - look at Twitter and Flickr, just to scratch the surface - have APIs that people actually enjoy using. And that’s not pot luck. It’s simply down to the fact that the APIs are easy to use, so people use them.

The Ideal Recipe

So, how do I create the perfect API, you ask? It’s a three step problem:

  • Understandability

    Designing the API to make it pure and simply understandable. Who wants to build anything with an API that you can’t understand? Simplicity is key.

  • Consistenicity

    Designing a consistent API. X must always mean X, Y must always do Y.

  • Resourcicity

    Providing documentation, examples and libraries for your API, as well as making it accessible and resourceful. It’s got to be easy to pick up and run with.

Okay, so I made all those words up, but you get the idea. These three points are vital to creating a programmer-pleasant API. And if you want people to use your API, you need to make it nice to use, otherwise people will ignore your API and use Dave’s instead. Or if Dave’s API is a pain to use, they’ll program the functionality themselves.

Upcoming

As there’s a lot to cover I’m going to break this article up into a series of parts (explaining the “Part 1”), which will be released over the next few weeks. I’ve drawn up a little Table of Contents to whet your appetite.

  1. Introduction
  2. Choosing your protocol
  3. API Structure and Resource-based APIs
  4. Documentation and resourcicity

I’m looking forward to writing the rest of this series and I hope you look forward to reading it!