The Technical Debt Behind Your Integrations Strategy
An integrations strategy promises to connect your software to all the other tools your customers use. Approached correctly, you can connect All The Things. But it’s not easy. With one or two integrations, maybe you can stay on top of the changes in just a handful of APIs. More than that, and you’d better have a team of people dedicated to maintaining your integrations.
All software has technical debt, the line of credit we take out when we commit concepts to code. The interest accrues as needs change while the original code remains. When the debt is not just the software we wrote, but also someone else’s API, that interest rate compounds. The technical debt piles up faster, lurking behind your integrations strategy, making your integrations more likely to break.
With over 1,000 apps integrated with Zapier, we obviously think an integration strategy is worth the effort—but it's also worth planning before you start work. And we’ve also learned a few things to help you make the most of your efforts.
Anatomy of a Single Integration
There are many reasons you might want to build a single integration. In the best cases, you heard from users that they want to use your product with another. Or you might want to fill known holes in your product, create co-marketing opportunities, keep your best customers engaged, and expand your feature list to acquire more users.
Once you’ve decided to build an integration, there are a few pieces needed to complete the puzzle:
- Use case: an opinionated approach to how your product will interact with the other.
- Exposure in your product: a way for users to discover your integration.
- Integration code: the software that performs the connection between products.
We believe that there’s more that needs to happen once you are code-complete, or else your integrations may become worthless. You need to tell people about your integration and support it in many other ways. Nevertheless, the three technical items above are the minimum requirements for a single integration.
Already, this single integration is more complex than a couple API calls. You need to figure out when data flows from your product, and when it goes the other way. You also need to decide what data is sent or stored. Finally, how will your customers use the integration within your product’s interface?
With answers to the above questions, you’re ready to write some code. You’ll need to determine how to authenticate to the other product’s API. Does it use basic authentication and if so, are you prepared to store user credentials? Most likely you will be using API keys or OAuth Tokens, but there are many differences in how APIs implement each of those. The decisions the other API's developers made will influence how the authentication flow works for your users.
Once your user is authenticated with the other service, you can make API calls to gather or add data. Many times you’ll want to react to new data within the other service. Hopefully the API includes webhooks and has designed their webhooks the right way to make set up easy on your users. Otherwise, you may need to poll the API periodically, or provide a special URL that users copy-paste into the other service.
Despite the rather small list of requirements for a single integration, you can see it can get complex quickly. A complete integrations strategy requires that many of these connections are not only built once, but also maintained. That’s where the technical debt comes in. A scalable approach is needed to succeed with many integrations.
The Pains of Maintaining Integrations
After you’ve built one integration–or several–the real work begins. While the initial integrations are factored into roadmaps and engineering workload, most teams are not as careful or realistic about what it takes to maintain what they’ve built.
APIs change, improve, and require you to adapt. And APIs disappear, for minutes, for hours, forever. The technical debt of API integrations is exponential.
APIs Go Down and Take Your App With Them
It is very likely that you will experience downtime of a single API you use. What happens when an API is inaccessible? At a minimum, your integration will not be usable. Depending on how you connect to those integrations, it could also impact other portions of your product.
As your number of integrations increases, so does the inevitability that downtime will become a daily expectation. At Zapier, connecting to 1,000+ APIs means we had to find ways to handle API downtime at scale.
In an effort to make API downtime less painful, our data science team looked at error rates and timeouts across millions of API calls. Using this data, we determined a threshold at which it makes sense to stop calling a poor performing API. We essentially press pause on all calls to the troublesome service until we detect that it’s reliable again. That can last minutes or hours, at which point we ensure to make any calls we missed.
Our approach may be heavy handed if you have less than a dozen integrations. We even fought these fires manually into the hundreds of integrations, but it took dozens of hours of engineering time every week. And that was even with tools we had already built, including automatic and manual retries.
APIs Are Inevitably Deprecated
An API that goes down for a short period of time is annoying, because it may take several hours of unplanned engineering time. An API that goes away completely (or changes drastically) may require weeks of engineering effort that you hadn’t scheduled.
Yet, API deprecation is unavoidable. It’s part of the natural API lifecycle. In most cases, an API is replaced by a newer version that has advantages. But sometimes features are removed in next iterations.
No matter the status of the new API, whenever an API is deprecated, you’re faced with sometimes difficult questions:
- Is your use case still supported?
- How much will the code need to change?
- Should you update the integration or remove it from your product?
The best case answers to these questions still put a lot of work ahead of your engineering team. Hopefully the other party has provided at least 90 days notice, but even then it can be difficult to squeeze into roadmaps.
You can’t necessarily plan for API deprecations, but you need to be aware they’re a reality of your integration strategy. It’s easy to take a “spray and pray” approach, where you try to directly support as many integrations as possible. Try instead to consider the effort required today as well as what it will take to maintain integrations in the long run.
API Authentication Methods Change
In addition to entire endpoint deprecations, you should expect APIs will also update authentication methods. While API responses may stay the same, these changes can often be even harder to support. From a user perspective, integrations are usually a one stop setup. They provide credentials or permission, and then you can make API calls on their behalf. They are rarely required to re-authenticate.
When an API removes an old authentication method, guess what happens? The user’s existing authentication is usually removed along with it. Unless the API provides an auth migration endpoint, you have to get your users to set up the integration again.
Before a user can re-authenticate, you need to write the code to use that new authentication method. A common pattern we’ve seen is moving from API Keys to OAuth. While a key is a simple way to start, user experience and security needs often dictate moving to a streamlined, revocable approach.
Just because an API uses OAuth doesn’t mean it’s going to be like all the other APIs that use OAuth. Despite being a standard, we’ve encountered so many flavors of the authentication method, we have an inside joke about OAuth Butts. “This API supports OAuth, but…” begins the documentation before describing the little tweak necessary to successfully integrate.
APIs Get New Features
While API deprecations and other breaking changes are a pain, additional capabilities should be welcomed. However, that is rarely the case. Engineering teams are usually on to the next project by the time new features are available in an API with which they already integrate. Unfortunately, without the threat of breaking changes to influence the roadmap, most companies never update an integration once it’s complete.
Let’s look at a hypothetical example of how this might play out. You’ve excitedly integrated your app with a marketing email service. Your users can connect their account so contacts in your software are automatically added to a mailing list. It works great and your customers are thrilled—this is the promise of API integrations coming to fruition.
Months or years pass. The marketing email service adds a new tagging feature to help segments lists. They add new API calls to expose the tags. Now your customers, who also use the marketing email service, expect your integration to support tagging. Alas, you haven’t updated your code to use that new version of the API. And your integration still works the way it was built. Momentum is not in the direction of adding tags to your integration.
The above example shows that customers expect integrations to work. Granted, this is a hardware situation where it may not be possible to provide support retroactively. However, your API integrations are software-based, and very likely capable of being supported. Yet, the more integrations you have, the harder it is to stay on top of the latest for each API.
Staying Up With Your Own API
So far we’ve only talked about the side of the integration that you don’t control. It should be much easier to keep up-to-date with your company's API. Yet, you can still find yourself snagged periodically by technical debt.
The Importance of Dogfooding
You don’t always need to use your API to build the tool your customers use. Often, backend code will connect directly to databases to pull account information, for example. However, this ignores the advantages of eating your own API dog food, or “dogfooding.”
Even in this era of microservices, where internal software is structured as single-purpose APIs, there are often private endpoints. When you use APIs not available to others you:
- Give your engineering team twice the maintenance work
- Risk divergent feature support
These two are obviously interrelated. When there’s more to keep updated, engineers will often support the minimum necessary. That usually means your private endpoints can do more than your public ones, without any good reason for the difference.
Maintaining Your Side of the Integration
Just because your internal API supports your new features does not mean that your integrations remain updated. It’s like downloading the latest server patch, but not installing it. Those new capabilities in your API are only useful if you integrate with them, which includes connecting them to other services.
Let’s say you are the marketing email service mentioned earlier. When you added tagging to your software, your dogfooding ensured that it was also available via the API. But did you ensure that the integrations you wrote last year also take advantage of tagging? If you’re like many of us, likely not.
The situation should be no different with you on this end of the integration. You still need to expose that functionality in all the other apps where it makes sense. Your customers are counting on it.
Enabling Others to Build Integrations
Wouldn’t it be nice if you didn’t have to write all these integrations yourself? That’s the promise of a strong API program—you can encourage others to connect to you. If you aren’t dogfooding your API and keeping it in feature parity with your product, you’ll have a harder time attracting and keeping developers.
You’ll hear plenty of advice about the importance of great documentation for your APIs, including from us. Before you get there, though, you need a product people love and an API that fully supports the use cases customers want. That, plus a little business development, can land you integrations that someone else will maintain.
If you want others to build on your API, you’ll also want to be ready to answer questions from developers. That means routing support tickets to engineers or staffing up with someone else who can authentically answer technical questions.
The 1,000-in-One Integration Platform
It took us six years, but we currently integrate over 1,000 APIs. That’s a lot of building, monitoring, and maintaining. Our 2+ million users count on connecting to these SaaS tools to run their businesses and lead productive lives, so it’s well worth the effort.
The Zapier Developer Platform makes all these integrations available to you for free. As you’ve seen, there are a lot of factors to consider with writing your own integrations. We’ve removed many of the concerns about technical debt. When you maintain your one Zapier integration, the other 999 ride along in your sidecar. Start building today.
Comments powered by Disqus