1. API Design Tutorial
2. API Design: Lots of Upfront Design
3. API Design: Keep it Small and Focused
4. API Design: Don't Expose More than Necessary
5. API Design: Provide Sensible Defaults
6. API Design: Optional Abstractions
7. API Design: Central Point of Access
8. API Design: Don't Force the User to Assemble Components
9. API Design: Avoid External Dependencies
10. API Design: Avoid Logging in your APIs
11. API Design: Design for Testing
12. API Design: Design for Easy Configuration

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.