API Design Tutorial

Jakob Jenkov
Last update: 2014-05-25

Having developed API's and components for about 8 years now, some 5-6 years of those open source
API's (at the time of writing in 2009), and having used numeral API's developed by others,
I have slowly started using a set of guidelines when developing API's. In this tutorial
trail on API design I will attempt to write those guidelines down.

With the word "API" (Application Programming Interface) I generally refer to pieces of code that are
to be used by others as part of their applications.

These guidelines may not be the only one that applies to sound API design. It's just the ones
I have come across, og thought of so far. I may expand this trail over time.

If you have anything
to add to this set of API design guidelines, or anything to comment, feel free to send me an email.
You can find the email address on the About
page.

Here is a short video introduction to this API design guide. It explains the design philosophy
behind the advice given in this guide.

The Primary Goals of API Design: Functional Software Elegance

The primary goal of an API or component is to solve some problem the user has. The secondary,
but still important goal is to do so with as little effort required from the user as possible.
Third, your API should not create any new problems for the user. I have summed that up in this
sentence, which is by the way also how I define the concept of "Functional Software Elegance":

Solve my problem, with minimal effort from me, and don't get in my way.

This means that the API should be:

As easy to use as possible.

As easy to learn as possible.

As flexible as possible.

Should actually solve users problem.

Should not create new problems (e.g. by having annoying limitations)

You will see these goals reflected in many of the tips in this tutorial.