A couple of weeks ago I was speaking with one of our clients about API design. I has reminded of the conversation when checking out the YELP API this morning as part of working we are doing on a joint venture called SocialGrub. Pretty much every web-based service these days has some sort of API. An API, which stands for Application programming interface, is simply a mechanism that allows developers to get content from (or create it in) your service or application programmatically. As developers, we all have to design them to be intuitive and easy to use (for other developers). Here are some suggestions when designing an API:
- Call or method names should be intuitive, avoid long or confusing names
- Support multiple file formats for output. Popular formats include XML, JSON, and serialized PHP
- Consider having a JSON version (or serialized PHP/Phython) of your API. XML API responds tends to get large rather quickly. Consider using shorter node/element names (but try and keep them intuitive)
- Balance file size with node/element/method name intuitiveness
- Document your API, it always helps
- Include examples calls in your API as well
- When possible avoid keys for your API unless they are necessary
- Allows you to track/control usage but also adds complexity and time
- Provide platform specific SDK (PHP, C#, JS, i.e.) or sample code whenever possible
- You an also encourage your developer community to share their sample code and examples
- Study other API’s to understand best-practices, standards and get a good ideas of what developers will expect.