>API Design is easy…Good API Design is HARD

>

API is Forever.

Wise old Programmer

Note: I highly recommend watching “How to Design a Good API & Why it Matters” by Joshua Bloch.

Any time we write code we are fundamentally writing an API. So writing an API is fairly simple, we do it every day. Writing a good, simple, and clear API is harder. The work I’ve been doing on the Psychopath Processor has brought me face to face with the reality that all of the code we write when we make it publicly accessible through the Export package osgi bundle, effectively makes changing that API difficult. It does not matter whether it resides in an internal package, provisional package, or just a public package. As soon as somebody uses that internal API, it fundamentally becomes difficult to change it.

When do you make something API and when is it considered a supported API? In my opinion that will evolve as the project evolves. If you have a relatively new project, much of the API is going to change and change rapidly. There will be breaks possibly from milestone to milestone, and maybe release to release. However, as the project matures the API will mature and stabilize. (Note that this is where at times I think the yearly release train can be detrimental to new projects. It may push them out to a wider audience than the project is mature enough to handle yet.) Now where that API resides (whether internal, provisional, public) does not really matter. As soon as you move it from one package level to the next, you have basically broken adopters that are using the code.

So, how can we address the issue of providing supported API? There are two schools of thought.

• Code First – write some internal code, and then come up with the public contract.
• Contract First – create the requirements and design the API to the requirements.

Definitions may vary on these depending on perspective. The first is the approach that many projects seem to take. The later is an approach that is best supported from a programming aspect of Test Driven Development or Behavior Driven Development.

Personally, I think an API regardless if it is designed in a Code First or Contract First has to be used by its own developers. Using something different than what you adopters are using leads the adopters to start to access and consume your internals as API. It does not matter if you tell them not to access it, once you make it available for consumption, they will use it to get their job done. If you need it for your own work, your adopters probably need it as well.

We as developers need to consume our own dog food. The best APIs for our adopters tend to be the ones we use ourselves.