Good API design is essential to an API being used. The design of an API can be extremely daunting when you are just starting out with a new service so here are a few tips that can help you along the way to build a good, usable API.
-
Use your own API. The very best way to make sure your API is equipped with everything one would need to build something of value is to use it yourself. You will find that by using your own API to build your product you will work out a lot of kinks that would otherwise frustrate third-party developers.
-
Remove as many learning curves as possible. An example of this is to provide more documentation than you really need to by writing tutorials and not just flat documents. Code examples go a long way too. Provide "wrappers" or frameworks in common languages that help third party developers to "plug and play" with your API.
-
Follow standard conventions. This is related to removing learning curves, but you do not go against the grain. Try to utilize as many standards as possible. Chances are any third party developers that use your API will already be familiar with much of what you’re doing.
-
Support multiple response types. Do not assume that third party developers will only use the response type that you prefer. Supporting XML, JSON, PHP, and others is not too much more work and yet has a measurable impact on your APIs adoption.
-
Create and keep your own conventions. If you have one way to do things try to stick with it all the way through your API. An example of this would be how Twitter recently added a Lists API to their API and used the very same convention of interacting with that API as they do with accounts. This makes integration of new features dead simple and it will be appreciated.
-
Add some brains! If there are common actions that must be taken by all third party developers to interact with your API try to build those actions into the API. A good example of this is Flickr’s support for machine tags. Although a third party developer could do all of the work on their end to work with namespaces, predicates, and ultimately the values they are looking for – Flickr makes it easy by doing all of that work on the server-side. Taking the most common actions and rolling them back into the API will slowly build tremendous value in your API.
-
Open source as much code as you can. If you build any tools, frameworks, testing applications, products, or anything that uses your API – try to release that stuff as open source. This will help any new third parties to be able to see real examples of products that use your API. It would also be a good idea to promote open source projects to use your API as well so that the entire development community that you build can benefit.
-
Communicate with those using your API. Give the developers a clear path to communicate with you about your API, their applications, or anything they may need to get their jobs done. You will learn a lot about what you are lacking that you may have never thought of.
-
Drink a lot of caffeine.
These are just a few tips that I’ve learned in working with Viddler‘s development team to build our API. We’re currently working on the next version of our API, dubbed version 2, and we’ll be making massive improvements to the way that the API works, is documented, and how we use it internally. We’ve learned a lot over the last few years and we’re taking all of the tips above and everything we’ve learned from our development community to build what we think is a much more solid offering.
I hope that if you are building an API you can learn from our experience, our failures, and our successes (and I’ll try to share more of them here). If you have anything you’d like to add about good API design please do so in the comments.
The photo of the fire hydrant has nothing to do with this post but I liked it. It is one from my Lincolnton, North Carolina photo set.