Practical Advice to Good API Design
During a rare productive youtube session, I came across a talk on How to build good APIs and why it matters by Joshua Bloch (author of Effective Java). After watching it, I knew I had to take notes because the talk was too good to forget. So good in fact, that I wanted to share them with you.
Joshua managed to squeeze many topics into an hour, hitting both higher-level characteristics of a good API, the process of building one and some practical tips to building an API. So let’s jump right in.
Firstly, let’s go over real quick what an API is. This is not covered in the video, so if you already know, feel free to skip this part.
An API (Application Programming Interface) can be considered as a contract of how to communicate with the software behind the API. It defines what data you can fetch, what format it is in and what operations you can do on that data. Which means an API can be anything from a fully-fledged REST API or a set of methods you can call to operate on a list.
According to Bloch, there are certain characteristics you can aim for to design a good API.
Characteristics of a good API
- Easy to learn
- Easy to use, even without documentation
- Hard to misuse
- Easy to read and maintain code that uses it
- Sufficiently powerful to satisfy requirements
- Easy to evolve
- Appropriate to the audience
While these characteristics are quite abstract and hard to implement, they can be used as a guideline. How to achieve these characteristics is what the rest of the post is about.
Process of building an API
The first step of building an API is to start with the requirements. However, beware of proposed solutions by stakeholders and try to extract use cases instead. Figure out the exact problem you are trying to solve instead of how the user wants it solved.
Once you have the requirements in place, start small. Write up a maximum one-page specification.
Anything larger than that and your ego becomes invested. Sunk cost fallacy kicks in…
