Thursday, January 20, 2011

Designing Good Web APIs

I am not going to claim eons of experience in designing good APIs. I am going to approach it from the background of a developer who has to use and integrate with them.

What makes a good API? Here are some of my tenets:

1. Make your API calls as RESTful-like as possible

Because this term has evolved quite a bit I am going to stick with the primarily principles. Make API calls nouns describing "what" and not "do something".

2. API calls should have defaults.

Don't give me 100 required parameters just to see some action. Try as hard as you can to give me a basic call so I know I am doing something right. Along with this is to keep a minimum of API calls. The more calls you have documented the more I have to figure out which one it is I am suppose to be calling to get the right information. This is an area where I actually do want to be spoon-fed.

3. Use HTTP basic over SSL for authentication.

If you have the time and energy also support OAuth. The reason I hesitate with going straight to OAuth is because if you are just building an API your resources are probably limited. You are going to make mistakes. Getting it up and running with the lowest (and secure) common denominator is key.

Also use dedicated API keys that consist of an ID and a shared secret. Make sure these can be rolled.

4. Make your return format JSON.
For the love of god please don't use XML.

5. Version your API call in the end point:

/api/1.0/user/3
/api/2.0/user/3

6. Make the calls easily testable.

To me this means I can plug it into a web browser, type in some credentials, and get a response back. As a developer this makes me feel good early on.

7. Document your API calls with examples.

Especially the ones where I can click on a link and it does an API call for me. This is also great for testing your call.


A number of these guidelines are geared heavily to web development. If you are designing an API for a message passing system with latency and size requirements a good deal of this would change.