While we are developing an api or integrating a third party api into the system, we focus on the business problem. We also need to focus on the technical implementation as there are few areas we miss to notice, which may introduce bugs in the system or maintenance time. I have shared some of my learnings while we work with the api.
Publisher of API: Contract Design
Publishing an API not only involves the developing stage. Once after the business needs are identified in the earlier stage you need to finalise the contract for the API. Once you publish the api to the market, your consumers may provide feedbacks or improvements for new properties which may be of high value to them. When you are introducing new property, it should not bring any breaking changes to your existing consumers. Say for example, you want to expose the manufacturer of your product, you can publish your api in this format.
{
"manufacturerName": "Apple"
}If you want to publish the country of the manufacturer. You need to introduce a new property as manufacturer country. Instead of creating a direct field, create a nested field as manufacturer and add the related fields to it
{
"manufacturer": {
"name": "Apple",
"country": "India"
}
}Follow standards
At first you may be creating an API for one subscriber, they may need a date field in the “MM/DD/YY” format. Say you have a huge request for your api and each consumer may be needing a different format.
To avoid this problem, make sure you follow the standards while developing the API. Say when there is a date/time field involved, follow the ISO standards by mentioning the date in the “YYYY-MM-DD” format and for time; either use “z” for UTC and “+/-00:00” for specific time zones like IST.
{
"createdOn": "2020-11-16T04:25:03Z"
}Communicate with consumers
When there is a major release for the api, you may be communicating the release notes to the subscribers. Also communicate the changes with your consumers in a detailed manner prior to the release of what are the changes in this new version.
Also make sure there are no breaking changes introduced. If there is any subscriber with a breaking change, make sure they adopt to the new api changes. Avoid these situations in the future by having playbook for some examples of consuming the api. For example: Make the api idempotent, which means when making multiple identical requests to the api has the same effect as making a single request
Consumers of API: Contract validation
When you are planning to integrate any third party api into the system, we usually use swagger documentation to know behaviour of the api. On top of it, before you start to develop make actual api calls and understand the api. Try to understand the domain of the api and the scenario.
Don’t make assumptions
Make note of the error contract. You need to handle the negatives cases, what happens when the authorization is missing.
Conclusion
Test your solution end to end or have an automated integration test, even when there is a third party api is involved. Instead of planning a release for a huge audience, plan for a pilot release which involves minimal users. I hope including these steps in your process will reduce the maintenance and bugs.
