When you work with us at Everest, you’ll find that we are driven by several principles including putting your users first, lowering your total cost of ownership, and enabling you to get new features out the door faster with higher quality than your competitors can. Oftentimes we find that these discussions involve items like process, head count, and requirement clarity, which are all important, but one that needs more attention is the APIs of platforms you use.
APIs affect your business outcomes in many ways, including:
1. Speed - How quickly can you get or update data?
2. Data fidelity - Can you rely on the data you get being accurate?
3. Difficulty - An API that is difficult to use can increase the chance of using it wrong, which could lead to errors (like wrongly updating data)
4. Breaking changes - When API changes require your solution to be updated, then projects have to spend time that could’ve been spent on new feature development.
This is one of the many reasons why we are prolific fans of the commercetools platform for connected commerce. It has one of the most stable, easy-to-use APIs we’ve experienced. What makes it so great from our perspective?
The commercetools API is updated hundreds of times a year, and we can be blissfully unaware of this. Continuous delivery is one of the leading best practices in software development because it creates fast feedback loops, which has been a hallmark of agile for thirty years, and in order to pull it off you have to have high-quality change management otherwise you will break things and lose customers. Furthermore, when bugs or other unfortunate behaviors are found, the API can be quickly fixed. Continuous delivery is both a benefit of high-quality processes and a driver of them.
From an integrator’s viewpoint, backwards compatibility for all changes is perhaps the most important. As the commercetools API evolves, we are guaranteed that our existing use cases will not break. That is a pretty rare and high bar to clear. When we implement functionality in March 2022, we know it will still work in July 2022. This frees us to plan for and execute on more feature development.
How can an API be backwards compatible?
1. Adding new optional parameters is fine; adding new required parameters is not okay because that would require me to change my code to send you the new parameters or my code will break
2. Adding new data to the response is fine; removing data is not as I’d have to update my code if it used the data that had been removed
3. Response format (e.g., returning a list instead of a single item) should not change because I’d have to update my code to handle the changed format
4. When you need to make breaking changes, stand up a new endpoint (or query, if using GraphQL)
5. Be careful when changing the logic (especially in downstream systems) that process your API requests to ensure those changes do not affect backwards compatibility by violating one of the above bullets
The commercetools API is transparent about what the limits are when using it. This is crucial because constraints are freeing. When I know how many items or relationships I am allowed to create, I can properly plan for that from the beginning rather than having to make a mid-course correction.
As you choose platforms and systems to use, pay special attention to their APIs, as they will have a significant impact on your users, business, and competitiveness. APIs that are continuously delivered, backwards compatible, and transparent are keys to success.