How to Monitor Third-Party API Integrations

Many enterprises and SaaS companies depend on a variety of external API integrations in order to build an awesome customer experience. Some integrations may outsource certain business functionality such as handling payments or search to companies like Stripe and Algolia.

You may have integrated other partners which expand the functionality of your product offering, For example, if you want to add real-time alerts to an analytics tool, you might want to integrate the PagerDuty and Slack APIs into your application.

If you're like most companies though, you'll soon realize you're integrating hundreds of different vendors and partners into your app. Any one of them could have performance or functional issues impacting your customer experience. Worst yet, the reliability of an integration may be less visible than your own APIs and backend. If the login functionality is broken, you'll have many customers complaining they cannot log into your website.

However, if your Slack integration is broken, only the customers who added Slack to their account will be impacted. On top of that, since the integration is asynchronous, your customers may not realize the integration is broken until after a few days when they haven't received any alertsfor some time.

How do you ensure your API integrations are reliable and high performing? After all, if you're selling a feature real-time alerting, you're alerts better well be real-time and have at least once guaranteed delivery. Dropping alerts because your Slack or PagerDuty integration is unacceptable from a customer experience perspective.

What to monitor

Latency

Specific API integrations that have an exceedingly high latency could be a signal that your integration is about to fail. Maybe your pagination scheme is incorrect or the vendor has not indexed your data in the best way for you to efficiently query.

Latency best practices

Average latency only tells you half the story. An API that consistently takes one second to complete is usually better than an API with high variance.

For example if an API only takes 30 milliseconds on average, but 1 out of 10 API calls take up to five seconds, then you have high variance in your customer experience. This is makes it much harder to track down bugs and harder to handle in your customer experience.

This is why 90th percentile and 95th percentiles are important to look at.

Reliability

Reliability is a key metric to monitor especially since your integrating APIs that you don't have control over. What percent of API calls are failing? In order to track reliability, you should have a rigid definition on what constitutes a failure.

Reliability best practices

While any API call that has a response status code in the 4xx or 5xx family may be considered an error, you might have specific business cases where the API appears to successfully complete yet the API call should still be considered a failure. For example, a data API integration that returns no matches or no content consistently could be considered failing even though the status code is always 200 OK. Another API could be returning bogus or incomplete data. Data validation is critical for measuring where the data returned is correct and up to date.

Not every API provider and integration partner follows suggested status code mapping

Availability

While reliability is specific to errors and functional correctness, availability and uptime is a pure infrastructure metric that measures how often a service has an outage, even if temporary.

Availability is usually measured as a percentage of uptime per year or number of 9's.

Usage

Many API providers are priced on API usage. Even if the API is free, they most likely have some sort of rate limiting implemented on the API to ensure bad actors are not starving out good clients. This means tracking your API usage with each integration partner is critical to understand when your current usage is close to the plan limits or their rate limits.

Usage best practices

It's recommended to tie usage back to your end-users even if the API integration is quite downstream from your customer experience.

This enables measuring the direct ROI of specific integrations and finding trends. For example, let's say your product is a CRM, and you are paying Clearbit $199 dollars a month to enrich up to 2,500 companies. That is a direct cost you have and is tied to your customer's usage.

If you have a free tier and they are using the most of your Clearbit quota, you may want to reconsider your pricing strategy. Potentially, Clearbit enrichment should be on the paid tiers only to reduce your own cost.

How to monitor API integrations

Monitoring API integrations seems like the correct remedy to stay on top of these issues. However, traditional Application Performance Monitoring (APM) tools like New Relic and AppDynamics focus more on monitoring the health of your own websites and infrastructure.

This includes infrastructure metrics like memory usage and requests per minute along with application level health such as appdex scores and latency. Of course, if you're consuming an API that's running in someone else's infrastructure, you can't just ask your third-party providers to install an APM agent that you have access to.

This means you need a way to monitor the third-party APIs indirectly or via some other instrumentation methodology.

The challenge of monitoring outgoing API calls

In order to monitor third party API calls, you need a mechanism to log both the outgoing API calls from your application before it reaches the third party and also log the response.

Many APM agents capture metrics at the process level which are great for capturing infrastructure metrics like JVM threads profiling or memory percentage but are poor at capturing application-specific context.

A second challenge is that outgoing calls in your application are usually scattered across your own code and also scattered across all the vendor specific SDKs you are importing into your application. Each third party SDK has their own callbacks and logic to handle API communication.

This makes it hard to capture all outgoing API calls via a cross-cutting concern or centralized proxy unless you decide to not leverage any vendor specific SDKs or modify them in order to intercept the API traffic. A considerable amount of busy work that very few engineering teams have time for.

Real user API monitoring is the recommended practice leveraged by modern tech companies. Real user API monitoring looks at real customer traffic rather than scheduled probes.

This enables you to catch deeper integration issues such as specific access patterns that a health prove won't catch.

How we did it at Moesif

Over at Moesif we leveraged monkey patching and reflection to inject tracking code in the core HTTP client libraries for common programming languages to build a SaaS solution that tracks third party APIs.

Because the instrumentation is within the app itself, there is an opportunity to add business-specific context such as the original end-user who initiated the API call to logging specific response headers that give insights to rate limiting or other soft errors.

We can do this since most languages rely on a single or small number of core HTTP libraries. For Node.js, all HTTP communication is based on the http or the https module. For Python, the majority of higher level clients will leverage the Python requests library.

An example middleware for Node.js to instrument outgoing API calls is below:

var express = require('express');
var app = express();
var moesifExpress = require('moesif-express');

// 2. Set the options, the only required field is applicationId.
var moesifMiddleware = moesifExpress({
  applicationId: 'Your Moesif Application Id',
  logBody: true
});

// 3. Start capturing outgoing API Calls to 3rd party services like Stripe
moesifMiddleware.startCaptureOutgoing();

the startCaptureOutgoing() will monkey patch the Node.js http and https modules by overriding every method on the
http and https objects with our modified ones which intercept the outgoing API calls.

An example of how we perform the monkey patching for Node.js is below and the full SDK is also available on GitHub.

function _patch(recorder, logger) {
  var originalGet = http.get;
  var originalHttpsGet = https.get;

  var originalRequest = http.request;
  var originalHttpsRequest = https.request;

  http.request = function(options, ...requestArgs) {
    var request = originalRequest.call(http, options, ...requestArgs);
    if (!request._mo_tracked) {
      request._mo_tracked = true;
      track(options, request, recorder, logger);
    }
    return request;
  };

  https.request = function(options, ...requestArgs) {
    var request = originalHttpsRequest.call(https, options, ...requestArgs);
    if (!request._mo_tracked) {
      request._mo_tracked = true;
      track(options, request, recorder, logger);
    }
    return request;
  };

  http.get = function(options, ...requestArgs) {
    var request = http.request.call(http, options, ...requestArgs);
    request.end();
    return request;
  };

  https.get = function(options, ...requestArgs) {
    var request = https.request.call(https, options, ...requestArgs);
    request.end();
    return request;
  };

  function _unpatch() {
    http.request = originalRequest;
    https.request = originalHttpsRequest;
    http.get = originalGet;
    https.get = originalHttpsGet;
  }

  return _unpatch;
}

How to leverage monitoring

Just setting up dashboards and reporting on your API integrations is only half the story. There are numerous ways you can leverage this data to improve your customer experience:

1. Set up alerts when metrics are out of bound or has anomalous behavior. An easy way is through PagerDuty, Slack, or other channels.
2. Hold partners accountable to their SLAs. When your consistently running into latency issues or failures with a single vendor, let them know. If you already have a full audit log showing what happened, the partner may be able to tweak their infrastructure to better accommodate your access patterns or even refund you if they are failing contractual obligations.
3. Avoid downtime and ensure your own team is able to respond to partner issues. This may include turning off a feature via feature flags until the partner remedies the issue.

---

Looking for a complete customer-centric API analytics solution? Check out Moesif!

---

This article was written by Moesif CEO, Derric Gilling, for the Moesif blog.