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

Introducing API Design Principles

  Monday, April 11th, 2011

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.



API Design Anti-Patterns

  Sunday, March 27th, 2011

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.

Sketch Out Your API First

  Thursday, February 10th, 2011

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.

The pthreads API

  Sunday, February 6th, 2011

The POSIX pthreads standard provides a flat C API for managing threads. Eli Bendersky wrote an article that highlighted many of the good API design techniques used in that API. For example, it is simple and orthogonal, consistent, employs logical naming, uses opaque types that hide internal details, and uses attribute objects to reducing function parameter lists. This article is a good read for those interested in examples of good C APIs.

Your API Sucks

  Saturday, January 22nd, 2011

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:

APIs with an Appetite

  Monday, January 17th, 2011

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.

API Design as if Unit Testing Mattered

  Wednesday, January 12th, 2011

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!

Java API Design Guidelines

  Tuesday, December 28th, 2010

Eamonn McManus wrote this blog article about API design guidelines for Java. This includes some generic words of advice such as designing for change, being minimal, being easy to use and learn, etc. In terms of Java specific guidelines, McManus talks about the problems of using interfaces and packages, and provides specific advice such as using immutable classes, static final fields, and avoiding Cloneable.

Why are APIs Difficult to Learn and Use?

  Tuesday, December 28th, 2010

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.

Open APIs: State of the Market

  Friday, December 24th, 2010

John Musser gave a presentation at Cloudstock during Dec 2010 about the state of open APIs for the Web. He starts with the big picture, covering why you may want to create an API and the surge in new Web-based APIs that have appeared over the past few years. He then goes into the business of APIs, looking at various business models and scalability needs of successful APIs. The focus then turns to design and technology issues, such as protocols, data formats, styles, and authentication.

RESTful API Design

  Wednesday, December 15th, 2010

Brian Mulloy recently gave a presentation about Web API design at Saleforce’s Cloudstock event in San Francisco. He has provided a video of his talk that is well worth checking out if you’re interested in RESTful API development for web services.

Brian starts off with a poor unstructured Web API and evolves this toward a better design. He suggests that you should avoid verbs in your URLs and that you only need 2 base URLs per collection: one to access the collection and one to access a specific element. He follows the advice in the Wikipedia article on RESTful design that POST queries are used for creation, GET for reading, PUT for updating, and DELETE to remove. He also covers topics such as good ways to support pagination of results, specifying the response format, and versioning of your web service. This is a great overview of good Web API design, and it’s only 16 minutes long. Check it out:

API Design Interview Feedback

  Wednesday, December 8th, 2010

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.

Aphorisms of API Design

  Monday, December 6th, 2010

Larry Garfield will present a talk called “Aphorisms of API Design” at the Dupalcon conference in Chicago, Mar 7-10 2011. Here is the description of the talk:

Code that talks only to itself is not useful to anyone. Code that enables other code magnifies its power 10-fold.

But how do we enable other code, and those who write it? What makes a module extensible? What is that vague extra something that turns merely extensible code into an API, a library, and a cornerstone of other systems? How do we harness that power for ourselves?

Let us examine the Aphorisms of Good API design, and the 8-Fold Path of API Nirvana.

This session goes beyond how to write modules well to cover the question of how to write modules that spawn other modules and innovation by Coding for the Future.

Intended audience:
Module developers who want to write not just good code but code other developers will want to use. Site builders and evaluators who want to know how to tell if a module is “doing it the right way”. Site Architects who want to know what modules are likely to be extensible in the future rather than evolutionary dead ends.

See: http://chicago2011.drupal.org/sessions/aphorisms-api-design

Jenkov’s API Design Tutorial

  Sunday, November 21st, 2010

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.


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) 2022 Martin Reddy. All rights reserved. Login