It is a pretty basic concept—look at other competing or complimentary APIs in the space, before designing your own. This seems like common sense to me, but I look at APIs for a living, and I’m interested in finding the best API patterns across business or government sectors. Even though this topic seems like a no-brainer to me, I still encounter many folks who contact me to discuss their API strategy, but have not looked at any APIs, in the same genre as the one they are looking to enter--which tells me I should be writing about this topic on a regular basis.
My first advice to any API provider, looking to begin new API effort, is to look at as many of the leading APIs out there, as you have time for. Even if they aren’t in the same genre as your API, they are leaders for a reason, and do many things that you can learn from. If nothing else, at least look at the pioneers like SalesForce, Amazon, Twitter and Google—they know what they are doing.
Secondarily I urge developers to go look at any APIs that are doing the same thing, or portentially exist in the same genre, as your API. If you are doing a bookmark API, go look at Delicious and Pinboard. If you are doing an image API go look at Flickr and Instagram. Even if your API will be slightly different, you should look at all, accessible, patterns, that are similar to what you are trying to do do. Try to understand why these APis providers designed their interface the way they did, and actually make calls against the API, to see what you like, and what you don’t like about their approach.
Once you have looked at all the APIs you can, take the best patterns you found, and make it into your own. Even if you come back around, and still think your API design is superior, you will have learned something through the process—even if you learn what you don’t want to do, or just receive validation of your idea. If you haven’t done your due diligence, looking for other healthy API patterns in the space, you are wasting valuable development cycles, on something that may not actually be innovating, and moving the conversation forward.
