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

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/

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

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.

Michael Feathers, author of the book “Working Effectively with Legacy Code”, gave a presentation at SD West in 2007 about designing an API with consideration for how it will be unit tested. He presents recommendations such as avoiding static methods and avoiding final/non-virtual methods (although I disagree with the latter recommendation in my book, where I argue that being minimally complete is more important). He also presents a golden rule of API Design: “It’s not enough to write tests for an API you develop, you have to write unit tests for code that uses your API.” He also states that you should supply your tests to your users. I could not agree with those statements more!

• http://www.objectmentor.com/resources/articles/as_if_unit_testing_mattered.pdf (PDF)

Jakob Jenkov has compiled an extensive collection of tutorials on how to design good APIs. Jenkov summarizes the qualities of a sound API with the statement: “Solve my problem, with minimal effort from me, and don’t get in my way.” His tutorial is broken down into several sections, including: Lots of Upfront Design, Keep it Small and Focused, Don’t Expose More than Necessary, Sensible Defaults, Optional Abstractions, Central Point of Access, among others. His tutorial covers a lot of ground and offers a lot of valuable tips, including several code examples in Java to illustrate his points.

• http://tutorials.jenkov.com/api-design/index.html

C. Lawrence Wenham compiled a great list of API design tips, including concepts such as naming, consistency, reducing complexity, avoiding side effects, and avoiding boolean arguments. He also advocates for designing an API from the point of view of the client, rather than choosing the solution that’s easier to implement (which is perhaps an obvious statement but still all too commonly violated). This is a concise yet thorough collection of important concepts to bear in mind when you’re designing an API. Well worth a read.

• http://sites.google.com/site/yacoset/Home/api-design-tips

Most testing efforts are targeted toward testing the actual functionality of an API, i.e., what it is supposed to do. However, there is another class of testing called non-functional testing. This involves testing the quality of the software from the user’s perspective. It can involve things like performance testing, scalability testing, and security testing. The following article gives a comparison between functional and non-functional testing.

• http://www.lessons-from-history.com/node/83

A unit test is a white-box testing technique that a developer performs. White-box means that you write the tests with knowledge of the implementation of the API. There are many frameworks out there that help you write, maintain, and run unit tests for your code. Most of these are based upon the J-Unit style of unit testing. Wikipedia offers a good categorization of unit test frameworks that are available for C and C++. See:

• http://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C
• http://en.wikipedia.org/wiki/List_of_unit_testing_frameworks#C.2B.2B

This article provides a QA engineer’s perspective on API testing. It pulls out some of different types of testing approaches, such as unit testing and black-box testing, and provides some guidance on writing API tests.

• http://www.scribd.com/doc/9808382/Introduction-to-API-Testing

Note that the term “API Testing” is commonly used in the QA domain to mean programmatic black-box tests that a QA engineer writes.  However, I view the topic of “testing an API” as being wider than this, encompassing unit testing, integration testing, and non-functional testing, and performed by either developers or QA engineers.