Best Practices for Building API Integrations

📣 This post originally appeared as Best Practices for Building API Integrations on The Bearer Blog.
Modern applications aren’t built in silos. They rely on the features of other applications. This reliance can come in the form of open-source libraries, access to a wealth of data, or complex features distilled down into a consumable API. Incorporating third-party dependencies into your own project can be challenging. It comes with the benefits of faster development, and the downside of reliance. There is a relationship that happens when using a dependency. Your app benefits but it also gives back in the form of money, exposure, or data.

The most common way to bring a partner API into your application is through an API integration. In this article we will look at:

• What an API integration is.
• How you can use a client or SDK to make development easier.
• The benefits of documentation.
• Why you should be tracking the performance of your integrations.
• How to set up a strategy for remediating problems with integrations.

But first, what are APIs?

An application programming interface (API) is a hook into an application. It is a programming interface that allows your applications to talk to another application. You can use them to pull in data sources, handle complex actions, or bring features from other applications into your own. Most commonly these come in the form of web APIs and web services.

What is an API integration

The difference between an API and an integration is that an API integration is how your application connects to an API. It is like a translator between your code and their application, and it is how APIs communicate. So how does API integration work? It handles the differences, so both parties can do their job without worrying too much about the other. The integration takes the application programming interface from one web service or data provider and encapsulates part of its functionality in a way for another application to use it.

You likely have a handful in place already. Some common integration types include:

• Social login
• User accounts
• Customer relationship management (CRM)
• Tracking
• Payments
• Data (Travel, Finance, Sports, etc.)
• Cloud services and cloud apps
• Machine Learning

The landscape of APIs is huge! So much so that many APIs even rely on other API integrations themselves. While many developers are familiar with the broad-reaching partner APIs provided by companies like Stripe, Twilio, and the big social networks, there are thousands of domain-specific APIs that industries rely on. For example, a travel booking site relies on APIs from hotel providers, tourism boards, and airlines in order to provide their booking services.

If you are the consumer of an API, your application needs to set up a secure connection to each API and send messages back and forth. These unique configurations are what make up the integration.

If you are the provider of an API, you need to offer a full experience. Guillaume, our CEO at Bearer, puts it like this:

API Integration is about product and feature, about UI/UX, engineering, but also about Ops (scaling, rate limiting, securing, logging, etc.) and in the end maintenance.

Even as the developer of your own application, others on your team will use any integration you build. This means it needs to be accessible outside of the scope of a single use.

How API Integrations work

One way that integrating with third-party, or partner, APIs can be easier is by using a client or SDK. API clients handle much of the overhead when interacting with an API. They can handle common tasks like:

• Authentication
• Error handling
• Encoding requests and parsing responses
• Simplifying requests
• Offering a better user experience than direct usage

Many large APIs providers offer a client for popular languages, such as Ruby, Node.js, PHP, and Python. For example, Google Maps is almost entirely SDK-based with support for mobile operating systems and web platforms. In cases where a client is not provided, you can still make requests just as you would with other web services. Through one of the three common API types: REST, GraphQL, or SOAP. Many of these have sets of API creation standards in place, such as the GraphQL specification and the Open API spec for REST APIs, which make them easier to learn.

While each will require your application to integrate differently, familiarizing yourself with the conventions can make API integration development easier.

You can sometimes find the APIs you use on an API integration platform. These are marketplaces that exist to make integrating with the programming interface easier. The downside of these platforms is that they add an additional dependency, sometimes increase latency, and may not be as up to date with the API provider's current features. If resources permit, it is better to avoid an API integration platform and instead develop integrations for your own applications.

Familiarize yourself with the API documentation

Whether you consume the partner API through a client, SDK, or requests directly to the API, you will need to be familiar with the surface of the API. The surface is the area your application can interact with. For clients and SDKs, this refers to the methods you will access. For APIs where you are making requests directly, the surface is the endpoints and data types you will access with each API call.

The documentation for an API can make or break your experience. Especially when starting out with a new API. It helps to familiarize yourself with the types of services or data offered, as well as with the common practices. For example, an API to search for TV show metadata may offer a search endpoint that accepts keywords for a title, while the endpoint for a specific movie might require an internal ID that comes from a search. Knowing the expectations of the API your application is integrating will help you avoid errors during the integration process. For some tips on getting used to a new APIs documentation, take a look at our guide on the Best Practices for Navigating API Documentation.

Track performance

The work isn’t over once you set up your API integrations. While we all would like to “set and forget” an integration, the truth is that any dependency is also a liability. You can start by monitoring your API usage. Specifically, here are the metrics we think are the most important:

• Latency
• Response Time
• Availability
• Consumption
• Failure Rate
• Status Codes

Having data about how an API integration performs is as important as having data on how your own applications perform. The performance of an API directly impacts the performance of your application and, as a result, the experience of your users. While many providers will offer a status page with details about outages and downtimes, they do not provide up-to-the-minute details about each request. This is where monitoring tools, like Bearer, come in. They can provide insight into each request to provide much more than just an “up or down” status. Binary performance metrics also only tell part of the story. Success status codes can often lead to the assumption that everything is fine, even when other issues like latency may be slowing your app to a crawl.

Remediate problems

The best thing you can do when relying on a third-party integration is to plan for failure. Even the most popular, reliable APIs have problems. To make sure their problems don’t become yours, consider coming up with a strategy for remediation. Some approaches involve:

• Retry failed calls, when appropriate.
• Implement a circuit breaker to avoid a failure cascade.
• Integrate API monitoring tools to keep track of failures.
• Handle exceptions and errors properly with custom exception types.
• Use fallback APIs or cached data to ensure your application still runs as expected.

A remediation is a way of handling a problem when it occurs. While you can monitor problems and make decisions about what to do next time, coming up with a strategy to remediate problems when they occur is even better.

Take your integrations to the next level

Whether you use an API integration that comes from the API provider, or you've built your own, you should have better insight and control into how it operates.

At Bearer, we’ve built a service to handle remediation and monitoring for you. It offers observability into your API integrations without major code changes. Not only does it provide you with valuable insights into your APIs and notify you in real-time when problems happen, but our agent also remediates API failures when they occur.

Give it a try today and connect with us @BearerSH.