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

• Change is Expensive in the API's Public Interface
• Upfront Design
• What to do When you do Need Change

The agile community has long promoted the idea that "Change is Cheap". Don't over-design now. You can always change the design later.

This may be true when developing an application in which you have control over all parts. But when you are designing an API that is to be used by external users, the situation is different. The API becomes a part of somebody else's application. Change in the API may be cheap for you, but expensive for the users of your API.

Change is Expensive in the API's Public Interface

Your API will most likely consist of public parts and private parts. The public parts are the parts of your API that the client of your API interacts with. This is also called the public interface.

If you change the public interface of your API you risk breaking code that uses your API. Your users won't like that. Therefore you should be really careful about doing this.

The private parts are less sensitive. You can change the internal parts almost all you like, as long as it does not affect how the API functions.

Upfront Design

To avoid change as much as possible in the public interface of your API, spend a good deal of time analysing and designing how your API should function, and what the interface would look like.

Some of the issues you might want to think about could be:

• How will the public interface look?
• How will the API be configured?
• What defaults should the API assume?
• Should any of the API's abstraction layers be optional?

In fact, every topic touched upon in this tutorial trail on API design might be worth considering during the upfront design phase.

For my open source API's, Butterfly Components, I have spent a long time analysing what I wanted them to do, and how to get them to do, as well as about what public interface they should have. Even so, I have had to change the public interface a few times, to accommodate the requirements of the future, or correct the lacking analysis and design of the past.

What to do When you do Need Change

If you find out that you really really need to change the public interface of your API, here is what you might consider doing:

1. Provide an alternative interface, and leave the old interface in the API too.
2. Deprecate the old interface to signal to users that they should switch to the new interface.

After a few releases with a deprecated interface you might consider removing it completely. But give users of your API a chance to upgrade at their own pace.