Designing a successful Web API

Designing the most widely adopted Web API for a particular functional domain does not merely take to offer the best and most specialized functionality at the best price, as reading Adam Smith would suggest.

It takes two additional things:

1. reducing the cognitive load on the developer using the Web API, and
2. reducing his risks of using the Web API.

Reducing the cognitive load includes:

• Making it easy to find on search engines
• Not requiring registration for an API key to get access to a version of the API that is not production grade (for instance,  a version that is much slower than the production version)
• Providing multiple representations (XML, XHTML, JSON, plain text, binary, etc.) for messages and multiple language bindings for the most popular languages in the target developer community
• Good documentation, including a step-by-step tutorial
• Examples with source code
• On-line test tools that allow developers to test the functionality prior to coding
• Building upon what target developers already know. Depending on the target developer community, this may mean starting with a REST/WOA API or a SOAP/SOA API.
• Building upon what API users have already learnt so far about the API: learning one functionality should make the next one easier to learn. This includes using precise semantics and re-using them consistently, defining and sticking to naming and message structure conventions.
• A variety of one-to-many medias (wiki, archived mailing lists, chat channels, etc.) for user-generated support and documentation.

Reducing the risks involves:

• Being very clear upfront about what the API does and does not and how it compares with others (to reduce the perceived risk that the developer will spend time on something only to discover down the road that it does not address his requirements).
• Ensuring the highest quality, up-time, availability and performance for the production version, and providing evidence of your commitment to these goals by using long betas (1-2 years) for new versions.
• Ensuring backward-compatibility: code written for the 1.0 should still work when the 3.0 version of the API is out. This means that your application should support 1.0 to 3.0 concurrently until no one uses 1.0 any more, and that versions should be explicit in URLs (ex. http://mycompany.com/webapi/1.0/…).
• Providing evidence that the Web API will be around for some time, because it is backed by a sound business model that can sustain its growth, maintenance and developments.