• Increase font size
  • Default font size
  • Decrease font size

Wenham’s API Design Tips

  Sunday, November 21st, 2010

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.


Version Aversion

  Thursday, November 4th, 2010

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.


API Diff

  Tuesday, October 26th, 2010

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:


Web API Documentation

  Thursday, September 30th, 2010

Peter Gruenbaum wrote a great article on best practices for producing documentation for Web-based APIs. He notes the importance of auto-generating API documentation, including sample code, showing example requests and responses, and explaining authentication and error handling.


Doxygen

  Thursday, September 9th, 2010

There are many tools out there that will create API documentation automatically from the comments in your code. Doxygen is one that I have used a lot and also like a lot. It can extract documentation from many different languages, including C and C++, it works on Windows, Mac OS X, and Linux, and it has a huge degree of configurability. It’s also open source. Check it out for your API reference documentation needs.


What Makes APIs Hard to Learn?

  Thursday, September 9th, 2010

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.


API Design Matters

  Thursday, September 9th, 2010

Michi Henning wrote an article in ACM Queue called “API Design Matters” in which he suggests that changing APIs should be a criminal offense and that authors of poor APIs should be held accountable for their crimes. He notes that good APIs are hard to design and he presents some examples network and synchronization APIs that could be improved. He also calls for APIs to be documented before they are implemented.

Some comments on this article can be found here.


ABOUT THIS SITE

An Application Programming Interface (API) provides a logical interface to a piece of software and hides its internal details. This website is dedicated to a book on designing APIs for C++ and includes articles and links on API development.
 

SOURCE CODE

The book is accompanied by a source code package that contains many of the examples in the text. Download it for free.
 

OTHER BOOKS

Dr. Reddy has also published a computer graphics book called Level of Detail for 3D Graphics. Check it out too!.
 
Copyright (c) 2024 Martin Reddy. All rights reserved. Login