• 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.

The Temptations of Symmetry

  Tuesday, October 26th, 2010

Kevlin Henney wrote a white paper on patterns in Java called The Temptations of Symmetry. Here he suggests that software designs should be biased toward symmetry because symmetric designs tend to be simpler and hence easier to use. The paper includes sections on Returning What You Borrow, Not Returning What You Didn’t Borrow, Fault Injection, and Encapsulating What You Borrow. You can download a PDF version of the document from the following link:

API Design Guidelines

  Tuesday, October 26th, 2010

Ricardo Cabral has compiled a set of API design guidelines, including general guidelines and Java/C++ specific ones. This includes best practices such as being minimal, being complete, having clear semantics, being intuitive, and being easy to remember. Many of these come from the Qt API Design notes, but there are some further suggestions in there too, dealing with static and dynamic polymorphism, enums,  and reference/pointer use in C++. See:

Top 10 API Pitfalls

  Thursday, September 30th, 2010

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.

API Design for the Web

  Thursday, September 30th, 2010

The 3scale team have put together some tips and examples on API design. Their blog post is specifically focused at cloud computing, including applying the standard MVC pattern to cloud services and API anti-patterns in REST applications.

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 Usability Guidelines

  Thursday, September 9th, 2010

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.

Best Practices in Java API Design

  Thursday, September 9th, 2010

Bill Venners wrote several articles on object-oriented API design best practices in Java for a book that he was working on. This is a work in progress, and obviously focused on the Java language, but there are some interesting nuggets of information in there, such as maintaining a semantic contract, bundling services, and keeping your interface simple and focused. It appears that the book was never completed, however.

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.

How to Design a Good API

  Thursday, September 9th, 2010

Joshua Bloch is the author of the book “Effective Java” and has a long history in the Java community. He gave an excellent talk on API design in 2007 called “How to Design a Good API and Why it Matters”. While this is focused on Java, Bloch covers many generic principles of API design that are just as applicable to C++ API development, such as class design, method design, exception design, and refactoring API designs. This slide set is well worth your time reading.

Qt API Design Notes

  Thursday, September 9th, 2010

The Nokia Qt library provides a cross-platform application and UI framework for C++. It is often used to create user interfaces for programs that must run on several different platforms, but it also includes a large array of lower-level functionality, such as classes to handle threads, database access, regular expressions, networks, and XML.

Several of the Qt developers have written on the topic of good API design for C++. For example, Matthias Ettrich wrote an article on designing Qt-style C++ APIs that covers many good issues such as characteristics of good APIs, the boolean parameter trap, and the art of naming. See:

Also, Jasmin Blanchette wrote a document called “The Little Manual of API Design” that provides a similar treatment but with a bit more detail and covers more material on the design process and design guidelines. See:

Java API Design

  Thursday, September 9th, 2010

Jaroslav Tulach wrote the book “Practical API Design: Confessions of a Java Framework Architect.” Jaroslav also maintains a website to support the book. This site includes lots of tips on API design that, while focused on Java, still offer general insights for C++ engineers working on API tasks. His site also provides a Java source code download for many of the examples in his book.

You can also read a review of Tulach’s book here:


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.


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


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