Any experienced developer knows that coding the integration is only the first half of the battle.
After you’ve built your API integration, the next step is to set up logging and API monitoring (if not available at the native endpoint) to capture usage data to support the integration and keep your operations team in the know.
Your customers are depending on the “trains to keep running,” making monitoring and logging mission-critical to ease of use and user experience.
This post is a follow-on to our updated Definitive Guide to API Integration. Download the full guide for more in-depth content on integration best practices, from pre-build to post-build, or check out the blog series.
We often recommend partnering with your DevOps or IT Operations team to determine how to handle alerts and notifications from the endpoint regarding service outages, API changes, user experience, etc. Who gets notified and what warrants an alert?
But at the end of the day, the key point we want you to take out of this blog post is the criticality of API logging and monitoring - and the consequences of ignoring it.
Without effective API monitoring, you will likely face some common integration failure modes such as:
- Lack of insightful usage data
- No health checks
- Slow response times
- No tags on usage data
- Inconsistent error codes
These failures reflect poorly on your application and leave customers and end users frustrated. But fear not. We’ve taken a deeper dive into each of these failure modes to explain why they happen and how to overcome them. Read on for deeper insights.
Five API Monitoring Failures
1. Lack of Insightful Usage Data
The first failure is simply not collecting the integration usage data. If you don’t measure your integration stats or feed the data into your application team’s daily application performance monitoring (APM) tools, you’re missing out on a wealth of important user experience data. And missing out on this information leaves you a gap with what the experience should be and how it actually is.
Improve visibility (and, by extension, the user experience) by embracing the usage data from the integration and making integrations part of your core application. By passing the usage data to your application monitoring team, you enable your support team to understand usage patterns and gain the insights required to establish proactive support of your clients’ integrations.
A broken integration often feels like a broken app in the eyes of the end user. Usage data will enable you to troubleshoot more effectively.
2. No Health Checks
Keeping track of the health of the endpoint is your first line of defense to maintaining (and creating) an optimal experience. With frequent endpoint Health Checks, you can stay ahead of complaints from unhappy customers about the stability of your product.
We recommend automating Health Checks for your app’s integrations to continually gauge whether the endpoint is the issue or if your integration or app is at fault. This is one of the most frequent integration issues, so being able to accurately diagnose via a simple ping to the endpoint is a helpful step in reducing the burden on your developers.
3. Slow Response Times
Response time issues are among the most frequent complaints with integrated apps. The key for your operations team is to understand the response time from the endpoint to again isolate your application's performance vs. the performance of the endpoint you’re connecting to. Some endpoints are notoriously slow, so you’ll need to make sure that your clients are met with proper timing expectations given potential performance delays.
If slower response times persist, you can also choose to implement a cache or a number of other mechanisms to improve performance. Understand expectations, know what type of response times are expected from the type of service you are integrating to, and set goals for how quickly your API integrations need to perform.
4. No Tags on Usage Data
Tagging your usage data enables rapid filtering of your logs to isolate and debug issues. Tags are vital to enriching your reporting and dashboard experience, as they allow you to dig into granular data and to enact filters, searches, and queries.
For example, you can filter by customer, environment (e.g., prod, sandbox), integration (e.g., Salesforce, NetSuite), etc. to answer questions like: “what are all of the integrations used by Customer X?”, “who are all of the customers using the NetSuite integration?”, and “is this an issue with the prod or production environment?”
Without tags on usage data, you’re not enabling the full suite of visibility your development, CS/PS, and product teams need to be successful.
5. Inconsistent Error Codes
The fifth and final API integration failure we’ll cover here is not normalizing the error codes. Your operations team doesn’t have time to research every vendor's error code, so you should standardize to the error responses your application currently runs on. This will help your support team understand and react to errors more rapidly and efficiently. (Maybe you’ll even get a “thank you” coffee out of it…)
Ultimately, we advise that you normalize the error code while still providing a payload back from the endpoint showing how they display the errors. This makes error codes easier to handle but you don’t lose any information in the process.
One other key logging initiative to quickly mention: you should track the usage information for every API call that is made. Know what call was made, how long it took, and what the response code was. This way, if any errors or complaints come up, you have a record that you can use to troubleshoot.
Ready to get into more best practices for building (and maintaining) API integrations? Read the Definitive Guide.
