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

Ferenc Mihaly maintains a blog call the Amiable API where he posts various articles on API design. As part of this blog, he provides a checklist of dos and don’t in API design. The list is focused on the Java programming language, however, most of what Ferenc presents it applicable to other languages too. I really like the bullet list format and the use of verbs to produce a concise yet extensive set of general rules to consider when developing an interface.

• http://theamiableapi.com/2012/01/16/java-api-design-checklist/

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

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

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

Bj Rollison wrote an article on API testing in which he talks about the differences between unit, API, and GUI testing. He goes on to describe some of the key benefits of API testing, including: reduced testing costs, improved productivity, and higher functional quality. Bj concludes by talking about the relationship between developers and testers.

• http://www.testingmentor.com/imtesty/2011/12/01/api-testinghow-can-it-help/

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++).

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.

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.

• http://pycon.blip.tv/file/4878793/

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.

• http://www.danwebb.net/2011/2/10/writing-a-new-library-sketch-it-out-first

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

The Communications of the ACM published an article called “Version Aversion”, which discusses various approaches to using version numbers in a software project. Much of the discussion mirrors the content in my book, API Design for C++, including the use of major/minor/patch version triples, tips on when to bump each of these version numbers, and reference to more esoteric versioning schemes like the Windows operating system choice of Windows 95, Windows 98, Windows ME, Windows NT, Windows XP, etc. You’ll need access to the ACM Digital Library to read the article.

• http://portal.acm.org/citation.cfm?id=1831407.1831420

API Diff is a program that I wrote to let you compare two different versions of an API. The aim was to provide a tool that would simplify API reviews and to document everything that changed in a new version of your API.

It uses a C++ parser to provide specific support for C and C++ APIs, but can also handle other languages via a plain-text diff engine. It also lets you view all comment changes so that you can review any new documentation.  You can view changes in a side-by-side visual format and generate a report on everything that changed. The program is available for free for Windows, Mac OS X, and Linux, with additional functionality available for a small license fee. For more details, see:

• http://www.apidiff.com/

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