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

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

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/

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

Marsh Gardiner of Apigee recently gave a talk at Cloudstock 2010 in San Francisco entitled, “Your API Sucks: Why developers hang up and how to stop that”. While this talk is focused on the currently hot topic of Web-based APIs, Gardiner talks about a lot of general API design techniques. In particular, he urges API developers to focus on user experience and to remember that your API is a product and your developers are your customers. He states this involves putting yourself in your users shoes and giving them the information they need to succeed. Check out the 30-min audio recording of the talk and slideset at:

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

In one of his regular ACM Queue articles, George Neville-Neil (a.k.a. Kode Vicious) responded to a question about API design for a database service. In this article, he points out some poor ways of implementing such an API, resulting in a “fat” API that can be difficult to use and promotes poor coding practices like copying/pasting code. He then goes on to suggest improvements to the design and provides some examples of file I/O APIs that he feels are well designed. Finally, he notes that API design is an iterative process that improves over time as you receive feedback from developers who actually use your interface.

• http://queue.acm.org/detail.cfm?id=1229903

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/

Steven Clarke is a usability engineer at Microsoft and wrote an article for Dr. Dobb’s called “Measuring API Usability.” In this article he talks about applying usability to API development and how it can help to produce better interfaces. He also presents the cognitive dimensions framework, which offers 12 factors that impact the way a developer works with an API. Steven also talks about how to map these cognitive dimensions to different developer profiles, such as opportunistic, pragmatic, and systematic engineers.

• http://www.drdobbs.com/cpp/184405654

Martin Robillard of McGill University wrote an article for IEEE Software called “What Makes APIs Hard to Learn? Answers from Developers.” In this work, Robillard used survey results from 77 developers to find out the main obstacles they faced trying to learn a new API. The key indicators were issues with the design of the API and inadequate resources such as documentation. Read the article for more detail and nuance though.

• http://www.computer.org/cms/Computer.org/ComputingNow/homepage/2009/1109/rW_SW_APIsHardtoLearn.pdf

Mathieu Jacques wrote an article called “API Usability: Guidelines to improve your code’s easy of use.” This articles starts by defining the fundamentals of usability then proceeds to provide various usability guidelines such as good visibility, good conceptual model, good mapping, and good feedback.

• http://www.codeproject.com/KB/usability/APIUsabilityArticle.aspx