Observations on API and Mashup Management

API and Mashup Blog

API Tip of the Day: Reduce the Learning Curve

Be consistent when building your API, and try to use standard conventions when possible. This will reduce the learning curve for 3rd party developers.

API Tip of the Day: Self documenting code is an ideal

Read the API carefully as you write it.  Does it read clearly?  Can new users make sense of it quickly?  Twitter’s “statuses/mentions” is a good example – you’ll HTTP GET the mentions of the user account you’re calling from.  Readable APIs mean easy-to-adopt APIs.

API Tip of the Day: Involve the users early

Your API exists for the use of developers.  You’ll probably get it wrong the first time.  With a tight feedback loop between developers who use the API and those who build the API you can get it right quickly.  In turn these early users will help promote the API and help new users get productive.

API Tip of the Day: Don’t put verbs in your API

The accepted verbs for REST APIs are contained in the HTTP Request: GET and POST.  Realistically PUT and DELETE are not always available due to IT standards for security on web servers.  Try to design your interface from the point of view of using just GET and POST as your verbs.

API Tip of the Day: Learn from the masters

Joe Gregorio’s original column from 2004 is just as relevant today as it was then. It covers the four fundamental design questions that authors of a REST API must ask and answer. Find it here: http://www.xml.com/pub/a/2004/12/01/restful-web.html