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.

• http://www.howto.gov/mobile/api-design-documentation

Pamela Fox wrote about some great process that AT&T implemented to test the usability of their APIs. They invited several developers to come in and test out their APIs and give feedback on ways they can improve their developer experience. This is a great idea and fantastic way to improve an API based upon actual customer experience:

• http://blog.pamelafox.org/2012/03/api-usability-testing.html

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.

• http://37signals.com/svn/posts/3018-api-design-for-humans

As part of the Oracle lawsuit against Google, there is an interesting discussion going on about whether APIs can be copyright. Oracle argues that copyrighting an API is reasonable, claiming that APIs “contain many original and creative elements,” while Google notes that API design “is an art, not a science.” See Mike Masnick’s post on the topic here:

http://www.techdirt.com/articles/20110822/11242915616/side-show-oracle-google-patent-fight-are-apis-covered-copyright.shtml

My own point of view is that an API is a specification and does not exhibit any inherent behavior of itself; whereas an implementation that conforms to that specification has behavior and can involve intellectual property in terms of specific algorithms or implementation code. Moreover, an API is inherently public by definition – the point of creating an API is to allow other developers access to your implementation in a standardized way, and as such the API has to be public and open (such as via public header files in C++), versus a specific implementation that can be private and protected (such as the source files used to build a library file in C++).

David Zeuthen has written a long and detailed article on many of the design issues that are faced when trying to write a plain C API. He deals with aspects such as library initialization, multithreading, error handling, versioning, and testing. It’s well worth a read if you are interested in writing a library in plain C (rather than C++). David’s collection of best practices is split into 5 parts, as follows:

• Part 1: Base libraries, Library init/shutdown, memory management, threads/processes
• Part 2: Event handling and the main loop, sync/async I/O
• Part 3: Modularity, namespaces, error handling, OO design
• Part 4: Helpers, daemons, and testing
• Part 5: API Design, documentation, and versioning

The next iteration of the C++ standard passed the ISO technical committee review earlier this year and is scheduled to be approved this fall. This version of the specification is now referred to as C++11 (a reference to the year it will be approved). Jim Humelsine recently sent me the following link that provides a neat table of the new features of C++11, along with the status of their implementation in the gcc compiler. This resource was put together by George Flanagin and provides a succinct overview of the new features of C++11 as well as a great reference for those interested in trying some of these out in their own code. As I describe in my book, many of these new features allow for better C++ API designs.

• http://www.georgeflanagin.com/c++11/c++11.features/

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

Michael DeHann wrote a blog article relating some of the things he’s learned about good API design. This includes advice such as programming with a view to the outsider, naming classes appropriately, figuring out how to make your code better through experiencing bad code, provide documentation that obviates the need for users to ask you how your code works, avoid redundant code, avoid extraneous conversions where possible, keep logic with the class that owns it, avoid adding complexity to your code through many options, and finally test your code but focus on functional end-to-end tests.

Many of these design tips are not new, but Michael provides a fresh perspective on them that I think is worth reading. Check out his post at:

• http://michaeldehaan.net/2011/04/29/class-api-design/

Dr. Jaime Niño of the University of New Orleans has produced teaching materials to support his class on API development. This 6-page document covers a lot of the important API topics, from specification, documentation, design, implementation, and testing. These principles are illustrated with reference to the task of creating an API for data containers. Some of the words of advice include:

• Make the specification of the data type for the container as generic as possible
• Specify data containers via interfaces
• The data container interface must provide a cohesive abstraction
• Be consistent
• Be minimal
• Methods names matter
• Favor queries
• Minimize the number of commands
• Favor parameters’ type specified via interface types
• Use appropriate parameters and return types
• Avoid long parameter lists

You can view a PDF of the document here: API Design Principles in CS2.

This website presents an interactive architecture diagram of the Linux kernel. The diagram breaks the kernel into a grid of functionality and layers with the ability to pan and zoom the map. You can then click on a specific item to look it up in the Linux source code.

One of the problems of providing documentation for a large project such as the Linux kernel is how to make the information manageable to navigate. This interactive diagram is a great way to provide an overview of all the available APIs and gives developers a jumping off point into the API documentation (although in this case it is an index to the actual code, rather than a documentation index).

• http://www.makelinux.net/kernel_map.shtml

Christopher Scaffidi wrote this ACM Crossroads article in 2006 about the usability of APIs. He presents four challenges of API design and presents various strategies to overcome these. The challenges are: 1) inadequate documentation, 2) insufficient orthogonality, 3) inappropriate abstractions, 4) incomplete assumptions. In summary, he states that three themes occur when designing a good API: make the problem smaller, use an approach that is only fast on average, and find an approximate solution.

• http://portal.acm.org/citation.cfm?id=1144363
• http://web.engr.oregonstate.edu/~cscaffid/papers/pr_20060601_api.pdf

Ivanka Majic conducted several interviews with developers about what makes a good API. The three basic categories that she came up with as a result are that an API should be designed well, should have good documentation, and good support.

Under the topic of great API design, Ivanka provides various quotes from her interviews that support the qualities of consistency, predictability, and learnability, as well as noting that a good API is easily extended and gets better over time.

In terms of API documentation, she states that there should be an overview to explain what the API does, that documentation should be concise and logical, use navigation to expose content, and offer tutorials to help developers starting from scratch.

• http://design.canonical.com/2010/12/so-you-want-to-provide-an-api-for-the-world-to-use/