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.
Be consistent when building your API, and try to use standard conventions when possible. This will reduce the learning curve for 3rd party developers.
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.
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.
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.
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

