From the Trenches: Web API Design Best Practices

Romin Irani, January 6th, 2011

LokadWe 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?

Both comments and pings are currently closed.

5 Responses to “From the Trenches: Web API Design Best Practices”

January 6th, 2011
at 10:30 am
Comment by: Tweets that mention From the Trenches: Web API Design Best Practices -- Topsy.com

[...] This post was mentioned on Twitter by OriginalSignal. OriginalSignal said: From the Trenches: Web API Design Best Practices: We list over 2600+ APIs in our directory across various catego… http://bit.ly/emBXkF [...]

January 6th, 2011
at 4:31 pm
Comment by: Roger Jennings

AFAIK, Joannes Vermorel is male, so “her” should be “his”.

Cheers,

–rj

January 6th, 2011
at 5:36 pm
Comment by: Web API Design: Best Practices Discussed – HTML Goodies

[...] believes are worth sharing in his post entitled "A few tips for Web API design". …From the Trenches: Web API Design Best PracticesProgrammableWeb (blog)all 2 news [...]

January 7th, 2011
at 8:55 am
Comment by: Adam DuVander

Thanks Roger. Editor’s mistake (me). The body of the post had the gender correct before publishing, but I missed it in the excerpt. Fixed now.

February 27th, 2011
at 7:29 pm
Comment by: A few links useful for thinking about designing web APIs « Uncategorized « alfredoalvarez.com

[...] http://blog.programmableweb.com/2011/01/06/from-the-trenches-web-api-design-best-practices/ [...]

Follow the PW team on Twitter

ProgrammableWeb
APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.