5 key qualities of an API
Is my provider's API the real impostor? Or was it us who didn't ask the right questions during the investigation?
Most companies at some point in their lives find themselves in need of outsourcing a service, and companies with digital products are no exception.
The systems we develop often need other more complex subsystems to function, so complex that it's convenient to look for a third party that has already solved it.
For example, if our product needs to receive payments in different currencies, some subsystem will be responsible for providing the updated exchange rate, and some other will have to process the payment.
Many providers will give us an API along with its documentation so that we can integrate our systems. This connection or integration carries a risk; if the provider's API doesn't work well, our system will not work well, as the saying goes, "a chain is only as strong as its weakest link."
So, if we want our system to work well, it is essential that we find the provider with the best price/quality ratio.
As part of the technical team, our mission is to analyze if the APIs cover our use cases and estimate with the highest possible accuracy, the quality component of that equation.
There are many aspects that contribute to quality, below I tell you about five commonly overlooked key qualities during API analysis.
- Data Synchronization
- Performance and Availability
- Backward Compatibility
- Testability
- Resilience
Data Synchronization
Data synchronization is a process that occurs when we need to obtain information from the API to update data on our platform.
For example, the status of my movements depends on the status of your transactions, or my subscriptions represent your recurring payments, or my notifications are the result of your events.
The update can occur synchronously, meaning I have immediate feedback on the changes my requests make to the provider's data, or asynchronously, meaning there is processing that occurs without my system waiting for it. In both cases, we have to map the data of the API with ours; what changes is the moment we find out.
Additionally, asynchronous updating generally comes in two different flavors: either they send us a webhook to notify us that some data has been updated, or we have to set up a cron job that fetches data every determined time.
Some key questions we can ask related to data synchronization of an API are:
- How can I keep my entity X updated with changes from your entity Y?
- What happens if my server is down when you send me the webhook?
- How often should I fetch your entity Y?
Performance and Availability
The performance and availability of an API are so important that they should even be mentioned in the contract we sign with our provider.
Performance will be determined by the speed and concurrency supported by the API. On the other hand, availability will be subject to the percentage of errors obtained. There is no system that never fails. The API we integrate will fail sporadically, and it is a risk that we have to assume or mitigate. The strategy we implement will depend on the probability of failure and its impact.
For this reason, it is a good idea to audit interactions with our providers' APIs. That way, we have metrics that can be useful for claiming if necessary, and it also helps us debug errors.
Some key questions we can ask related to the performance and availability of an API are:
- How many requests per minute does your API support on average?
- What is the expected average latency?
- Could there be higher latencies than normal? At what times of the day?
- Could you share metrics from any stress test you have recently run?
- What is the uptime percentage of your system?
- What is the failure rate per day of your API?
You can explore how AI tools can optimize performance in software systems to find out more on this topic.
Backward Compatibility
Just as our system is constantly evolving by adding features and improving every day, our provider's system is also.
Backward compatibility defines how much the changes they make to the API will affect us. In other words, it will define how often we will have to maintain the integration we developed.
What changes are considered non-backward compatible? Some examples are:
- Adding mandatory fields
- Modifying the URL of endpoints
- Changing the format of responses
- Changing response codes
- Changing the name or data type of a mandatory field
While change is inevitable, there are strategies that our provider can take to reduce the impact, one of them is to version the API. A well-versioned API should ensure that all changes made to a specific version do not require us to modify our code.
It should be noted that API versions have a lifespan. The day will come when our provider decides to discontinue a version, and in that case, it is important that they notify us in advance so that we can plan it in our roadmap.
Some key questions we can ask related to the backward compatibility of an API are:
- How do you handle the versioning of your API? How often do you release a new version?
- How much notice will we receive about changes that break compatibility?
Testability
Testability is the ability of a system to be tested in its different flows.
We need to be able to test the different errors and responses that we consider in the integration, and it may be that our provider's test environment is not prepared to reproduce all the cases detailed in the documentation of their API.
Given that scenario, we run the risk that some flow has an error, and we do not detect it until it occurs in production. One way to mitigate this risk is to develop a mock API to reproduce the scenarios that the provider's sandbox lacks. Learn effective strategies for automating and testing software.
Some key questions we can ask related to the testability of an API are:
- Do you have a test environment we can integrate into low environments?
- How do I test the different error codes returned by your API?
Resilience
Resilience is the ability of a system to continue functioning even when an error occurs. As mentioned earlier, our provider's API will fail, and it is inevitable. However, there are ways to turn these failures into successes, one of them is to implement retry logic for errors. Discover how APIs play a key role in driving business efficiency.
Implementing retries is our system's responsibility, but being retryable is our provider's responsibility.
What should a retryable API have? Some examples are:
- Ensure that the retry does not duplicate operations
- Document which errors are final
- Maintain the same response for the same request
Many APIs use a transaction or idempotency ID in their requests to improve resilience. That ID is unique for each request, so they can cache the state of it and ensure that operations that should only occur once are not repeated.
For example, if we use an API to transfer money, we want to be 100% sure that that transfer will occur only once upon retry.
Some key questions we can ask related to the resilience of an API are:
- For which errors is it safe to retry a request?
- Do you have any retry limits?
- How long should I wait to retry a request?
- What happens if I send the same request twice in a row?
Conclusions
While there are several other fundamental qualities when investigating an API, those discussed in this post are the ones I have seen most overlooked and that have a strong impact on the quality of an API.
I hope this post helps you ask better questions to your providers and thus be able to precisely evaluate whether the integration will bring you more problems than solutions.
