What makes a great API ?

We are slowly moving towards a completely api-fied world. All the common services that we used to find so hard to deal with a few years back, have become super easy thanks to introduction of API’s. Today, every other person/business out there is developing an API to make an XYZ service more awesome (and gain some developer love). Hence, it is important to understand the principles behind designing good APIs. In this post, I’ll highlight a few practices/tips that I’ve learnt, designing a few and using different API’s.

So, what makes an API great ?

Valuable Service

A good API provides a valuable service. Stripe and Twilio are some of the epitomes. There are many more, but those two startups appeal to me the most. And what’s more awesome about providing a valuable service is that they help in hiding some of your API sins ;). Even if your API does not have good code or follow good conventions, you could still get away with it, if you provide something truly useful.

Understand your audience

It’s important to know your target audience before you jump into design. After all, you would measure your API success based on customer love, especially if your business depended on it (like Parse or Sendgrid). Do your homework and find out what your target audience is looking for. And then, give them what they want.

Planning

A good amount of planning goes into building a good API. And this certainly does not happen overnight. Before you jump into designing a good API, you must understand it’s purpose. Try and visualize how you want your API to look for the end user. You could write small snippets of how one would use your API and how the user input and API response would look like (popularly known as README-driven development).

Design

Seems pretty obvious that an API should have a great design. But the fact is  that “design” is too vague a term. So I guess I should say that it’s more about the choices that power the design. A typical list of design choices that you need to make would include:

• Protocol(s) to support
• Data Format
• Security
• Open Source ?
• Design Patterns to use
• Conventions and best practices to follow
• Versioning

There are many more choices when you think deeper, but I guess the above mentioned are good enough to start with.

Documentation

This is the most important metric that determines how good your API really is. You could compromise on quite a few things, but you could never get away with poor documentation. Using a great API with poor documentation is like using an iPhone for the sole purpose of making calls and messages. It just doesn’t make sense! There are reasons why iPhone is a “smartphone”. Similarly there would be a lot of reasons that make your API great, but they aren’t as intuitive when compared to the case of a smartphone.
So, boast about your super awesome API by writing a clean and crisp documentation. Give good examples, short and sweet tutorials and brief reference of all the features and methods of your API. And don’t forget to refactor the docs and make them better, just like your code.
Document each and every minor and major release of your API. This helps developers to keep track of the things that have changed, and possibly use them to their advantage.

Flexibility

It’s quite hard to figure out what makes an API flexible. A flexible API gives more control(and power) to the developer. A common example would be the ability to provide response in different formats like JSON or XML. Another example would be the ability to perform batch operations for different functionalities in your API. This may not be so commonly used, but when required it saves a lot of time by avoiding the user/developer from writing extra code for doing the same. And developers sure do appreciate that. After all, we’re a lazy bunch of people :P

Developer Support

This is another key metric that determines how awesome your API and/or how successful your business is. Let’s face it; we all love to use products that have a little chat widget on their website, that enables realtime communication with the developer/support team. That is precisely the main reason why services like Olark are so bloody awesome! They make the life of the developers and the users more simpler. You need to find more ways to provide good support to the customers. Ultimately, good experience is what makes us stick with a product/business. So make sure that you provide the best possible experience to your customers to make them come back for more.
I hope this would serve as a decent checklist for whenever you design an API for yourself or your business. It definitely would, for me.