Martin Fowler wrote about a way to approach RESTful Web APIs developed by Leonard Richardson. This presents 4 successive levels of concepts, from the simple “plain old XML” layer, through the notion of resources, http verbs, and hypermedia controls. Martin does a great job of explaining each of the layers through the use of figures and example XML data.

• http://martinfowler.com/articles/richardsonMaturityModel.html

The folk at apigee have distilled everything they’ve learned about Web API design over the last few years into a new free eBook called “Web API Design: Crafting Interfaces that Developers Love.” This collates many of the details from their various blog posts into a single reference, covering topics such as REST, handling errors, versioning, authentication, complementary SDKs, and many others. If you’re writing a Web API for your platform this is a great read.

• http://blog.apigee.com/detail/announcement_new_ebook_on_web_api_design

A new book on developing Web-based APIs is about to be published called “APIs: A Strategy Guide: Creating Channels with Application Programming Interfaces.” The book is written by Dan Jacobson, Greg Brail, and Dan Woods, who between them have an impressive background in developing real-world Web APIs. The book aims to educate executives and business development teams on the value and strategy for building Web APIs.

• http://shop.oreilly.com/product/0636920021223.do

Brian Mulloy at Apigee wrote a short article on versioning for Web APIs where he contrasts three different methods of including versioning information in a URL. These include using a timestamp or version number in the URL path, or accepting a version number as an optional parameter. Brian suggests using a mandatory version number as far left in the URL as possible, and using a whole number instead of dot notation for your versions.

• http://blog.apigee.com/detail/restful_api_design_tips_for_versioning/

If you want to read something a little longer than a blog article on how to build REST Web APIs then there are a few books out there that may be of interest to you:

• REST API Design Rulebook
• Restful Web Services
• RESTful Web Services Cookbook
• REST in Practice

In this Twilio Engineering blog article, Frank Stratton makes the point that computers don’t care about API design. APIs should be designed for human beings first and computers second. Using example Web APIs developed at Twilio, he talks about the need for having many eyes and minds see the design first, simplifying the surface area of your API, and how it is easy to add new calls but hard to remove existing ones.

• http://www.twilio.com/engineering/2011/10/31/apis-are-for-human-beings/

Daniel Rabinovich has put together a slide set on REST API design choices for Web-based interfaces. Daniel recommends using standard HTTP verbs, like PUT and OPTIONS. He also talks about being able to specify the returned fields (a performance optimization) and notes that selection, multiget, and search are REST violations with hidden costs (harder to cache or shard). Daniel covers a lot more topics, so see his slides for more details:

• http://www.slideshare.net/DanielRabinovich/api-design-choices

Dan Fairs wrote an article on Web API design with a focus on efficiency issues for mobile devices. The article starts off with a very good and easy-to-follow description of what a REST API actually is, including examples of resources, representations, and interactions. He then presents some real-world practicalities, such as dealing with bad HTTP clients and returning rich error responses.

In terms of mobile devices, Dan notes that you want to minimize the number of necessary round trip API calls, which means including more information in a single response, i.e., introducing data redundancy or denormalization. Dan presents a technique that allows clients to specify how much redundant data is provided in a response based upon a parameter in the HTTP Accept header. This effectively allows different clients to tune their behavior and request the appropriate representation for the given application.

• http://www.stereoplex.com/blog/mobile-api-design-thinking-beyond-rest

George Reese wrote an article to summarize his experiences using various SOAP and REST cloud computing APIs. His tips include:

Good: Support JSON and XML, prefer REST over SOAP, provide meaningful error messages and solid API documentation.
Bad: Avoid OAuth and HTTP authentication for system-to-system interactions, add throttling thoughtfully and carefully, avoid chatty APIs that require many calls.
Ugly: Don’t return HTML in your response body and understand how to return HTTP error codes.

For the full article, see:

• http://broadcast.oreilly.com/2011/06/the-good-the-bad-the-ugly-of-rest-apis.html

Trek Glowacki wrote an article about how to get your Web-based API right. He advocates the use of HTTP, using verbs to name end points, keeping your URIs consistent, using your HTTP status codes correctly, supporting multiple data formats, using OAuth or HTTP Authentication as appropriate to protect your users, and finally documenting your API well. For more details, check out the entire article:

• http://wonderfullyflawed.com/2009/07/02/get-your-api-right.html

John Musser gave a presentation at Cloudstock during Dec 2010 about the state of open APIs for the Web. He starts with the big picture, covering why you may want to create an API and the surge in new Web-based APIs that have appeared over the past few years. He then goes into the business of APIs, looking at various business models and scalability needs of successful APIs. The focus then turns to design and technology issues, such as protocols, data formats, styles, and authentication.

• http://www.slideshare.net/jmusser/open-api-ecosystem-overview-december-2010

This presentation at Google I/O 2010 by Zach Maier, Mark Stahl, Joseph Schorr, and Yaniv Inbar describes the Web API development process at Google. The talk covers some of the lessons learned about supporting REST partial updates, output formats, and calling styles. It also introduces the new API stack infrastructure being developed at Google. This stack lets Google engineers create a new API in a few minutes using a simple configuration file and web app, where the infrastructure provides authentication, caching, logging, and throttling for free. Very cool stuff.

• http://www.youtube.com/watch?v=nyu5ZxGUfgs

Brian Mulloy recently gave a presentation about Web API design at Saleforce’s Cloudstock event in San Francisco. He has provided a video of his talk that is well worth checking out if you’re interested in RESTful API development for web services.

Brian starts off with a poor unstructured Web API and evolves this toward a better design. He suggests that you should avoid verbs in your URLs and that you only need 2 base URLs per collection: one to access the collection and one to access a specific element. He follows the advice in the Wikipedia article on RESTful design that POST queries are used for creation, GET for reading, PUT for updating, and DELETE to remove. He also covers topics such as good ways to support pagination of results, specifying the response format, and versioning of your web service. This is a great overview of good Web API design, and it’s only 16 minutes long. Check it out:

• http://www.landlessness.net/2010/12/api-design.html
• http://rndsolutions.net/2011/10/restful-api-design/

Rick Nucci wrote this article exposing 10 of the most common API pitfalls that he has encountered in Web services code (also known as Software as a Service, or Saas). His list includes problems such as exposing operations instead of objects, constantly changing the API on your users, not thinking about performance issues such as throttling services, and getting caught without a strategy for your API.

• http://www.techcrunchit.com/2009/11/08/the-top-10-most-common-api-pitfalls