Great API design matters
“API-first design” will pay off in the long term
SpaceX docks the Crew Dragon spaceship to the International Space Station after a 19-hours journey since it lifted off from NASA’s Kennedy Space Center in Florida. Great achievement as a result of lots of smart work. Imagine getting all the way up there to realise the interface has changed, and it won’t dock. It would be too late to blame requirements, design, dev and/or test. And another iteration would come with an expensive price tag.
The International Docking Adapter (IDA) [2] is a spacecraft docking system that allows different countries/companies to develop their own modules and be able to dock them to the International Space Station, SpaceX being one of them.
In order to make the adapter a reality, they first understood the problem, defined and agreed the contract between countries, each country/company simulates and tests their modules in the lab and then implement.
Interfaces and great design matters. IDA illustrates clearly the point and promotes extensibility, modularity and technology independence. Similarly, adopting an “API-first design” approach can bring home lots of benefits. This approach states that first we understand the problem, define the contract, simulate/test, get feedback and implement later.
An API-first approach means that for any given development project, your APIs are treated as “first-class citizens.” An API-first approach involves developing APIs that are consistent and reusable, which can be accomplished by using an API description language to establish a contract for how the API is supposed to behave. Establishing a contract involves spending more time thinking about the design of an API. It also often involves additional planning and collaboration with the stakeholders providing feedback on the design of an API before any code is written. [1]
Let’s review the key advantages of “API-first design” approach [3]:
Parallelise work
The service provider and the consumer can work at the same time towards a shared goal. For instance, the consumer can mock the API and keep moving forward even if the provider is not ready.
Technology independence
Provider and consumer can be implemented using different technologies depending on requirements and/or team skills.
Clear expectations
Coding against a contract/interface definition allows both teams to develop and test up-front even if the other team hasn’t finished or is not ready for integration.
Hard to misused
As a result of having clear expectations, we end up having well documented specifications that developers understand and are happy to follow. This reduces the likelihood of unintended usage.
Lower development effort and cost
Creating the contract is many times cheaper than implementing it. After the contract is reviewed/exercised by stakeholders, and we have achieved some level of confidence, then we embark on development.
Better Developer Experience
The fact that contract is defined up-front provides a good incentive to achieve good levels of documentation, which majority of it will be produced automatically based on the contract. This also ends up increasing discoverability and hence reusability.
Avoid the API afterthought
Sometimes APIs are created after a system has been developed as an afterthought in which case the API ends up being tightly coupled with the source system. This approach provides a framework that allows you to avoid this situation with an upfront design.
References
- [1] Understanding the API-First Approach to Building Products
- [2] Docking and berthing of spacecraft
- [3] Implementing an API-First Design Methodology
Disclaimer
This is a personal article. The opinions expressed here represent my own and not those of my employer.
