The US Federal government has published a set of guidelines for government agencies that want to design Web-based APIs. This includes recommendations on authentication, keys, documentation, and code samples; with links to examples of Web APIs in the .gov domain.
|Monday, December 3rd, 2012|
|Tuesday, April 24th, 2012|
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.
|Friday, March 23rd, 2012|
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.
|Wednesday, December 21st, 2011|
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.
|Sunday, December 11th, 2011|
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.
|Sunday, November 6th, 2011|
|Friday, November 4th, 2011|
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.
|Monday, October 3rd, 2011|
Noah at 37 Signals wrote about API design for Web APIs. The key point he makes is about the need for strong documentation and having that documentation in an easy-to-search format. He then talks about authentication, advocating that an API offers multiple authentication schemes. Finally, he talks about building REST-like interfaces.
|Monday, September 19th, 2011|
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:
|Friday, June 17th, 2011|
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.
|Thursday, June 9th, 2011|
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:
|Friday, May 20th, 2011|
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:
|Sunday, March 27th, 2011|
Google’s Alex Martelli gave a speech at PyCon 2011 focusing on API anti-patterns, which he defines as counterproductive behaviors that are often systematically repeated. He states that the worst anti-pattern is not having any API at all, and the second worst is not having any design (an accidental API). Most of the talk is aimed at a process or design level, though a couple of specific code examples are given. For example, Martelli talks about the fact that a lot of software is overdesigned, but when you’re dealing with an API it’s actually good to spend a lot of up-front time thinking about future expansion and evolution before release. In terms of designing a good API he suggests thinking about 3 ways to implement your API: the common concepts will be the core functionality that should be in your API. He also suggests that you should use your own API as much as possible. Finally, he spends some time talking about choosing to do something one way, not two ways, i.e., taking a stand and making a decision. The talk is just over 40 mins and offers some great high-level insights into how to go about designing a good API, be it C++, Python, or Web-based.
|Thursday, February 10th, 2011|
Dan Webb wrote an article about API design where he suggests that you should first think about how you would like your interface to be used, before diving into details like class and function design. He argues that your API has to be simple and fun to use, providing the example of the Web-based jQuery API as an exemplar of this goal. I agree with Dan’s points: user-oriented issues such as the simplicity and usability of an API are often overlooked to the detriment of a library’s success. Dan also echos other suggestions that I make in “API Design for C++” about providing a simple interface for common operations but also enabling more complex operations with a more advanced underlying API.