From the Trenches: Web API Design Best Practices

Romin Irani, January 6th, 2011

Comments(5)

We list over 2600+ APIs in our directory across various categories. As we move into the new year, we are likely to see more the best practices for API providers to meet developer expectation,s while at the same time meet the scale that is expected from the most heavily used of APIs. Recently tips from the founder of the Lokad API, a sales forecasting service, summarized some of her tips for API design.

In his post, A few tips for Web API design, Joannes Vermorel, explains what Lokad learned while iterating through version 3 of its forecasting API. There were lessons learned during v1 and v2 of their API, which Vermorel succinctly captures as useful tips that are worth sharing.

Vermorel and company had to learn these the hard way. If you’re building an API (or laying the groundwork for your next revision), it would be good to keep them in mind:

• Full API Stack Ownership: Be prepared to take full ownership of the building blocks like XML,SOAP,HTTP since problems can happen at any level. Understand the protocols well. Teh blog post mentions how Lokad settled for REST over HTTP instead of SOAP to help narrow down when an issue occurs.
• Be minimalistic: Have bare minimum number of methods that are clear in their functionality instead of a large number of methods. The blog post gives an example of how they reduced the number of methods from 20+ to 8. Developers will also be clear in their choice of methods rather than having several redundant methods overlapping in functionality with each other.
• Idempotence: The network is unreliable and the same call is likely to get retried several times. Make sure your API can handle duplicate calls without causing duplicate results. If you’re curious about the term, Wikipedia has an explanation.
• Explicit Input/Output limitations: Be explicit in your API documentation about the amount of data that you can handle in your input and output messages. This will help to guarantee a certain minimum amount of response.

Next Generation API design is not just about having an API, but having a great API. Consider the above points as you try to get your API right. What other best practices do you follow for your API?