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.