Better Practices for Building Integrations

Let’s talk a bit about the purpose of an integration. A good integration provides benefits to both companies involved. It doesn’t make sense for you to come to me and say, “I want to scrape all of your data and serve it within my app” unless there is some sort of benefit for me. I’d only do this if you can combine my data with some other data and show something interesting.

For example, in Amplitude’s two-way integration with Braze, we allow our customers to send interesting user cohorts to Braze. When those cohorts are targeted with marketing campaigns, Braze sends us system events, which allows customers to understand those events in the context of their app. They would then be able to answer questions like, “After a user clicked on a push notification, did that user actually use the feature that the notification directed them to?” This sort of question couldn’t be answered by either product alone, but the integration between Amplitude and Braze makes it possible. By integrating, we make both products more valuable to our customers.

While working on integrations at Amplitude, here are a few things I learned about what makes integrations successful.

Good integrations start with customers

At Amplitude, we are big fans of customer development partners (CDPs), who help us build and test our new features. As soon as we have an idea for a new feature (or even just a problem space), we start talking to customers about it. At the early stage, we try to understand their current problems and what we can do to solve them. Later on, we might show them mocks for new features. After the features are built, we enable them first for these customers and get their feedback.

Whether the integration request comes from partners or from our customers, the first step is to find at least 2-3 customers who are interested in using it. If you can’t easily find customers who will use the new feature, then maybe you should ask yourself whether it’s a good idea to build that feature. Whenever a partner makes a request for us to build an integration, my first question is, “Who is going to use it?” If that partner can’t give me a list of customer names and use cases, then I’m inclined to make it a low priority.

Consider scale and speed

Any time you exchange data between servers, you need to consider the scale of the data and how quickly it needs to be processed. Sending 100 records per hour is a lot different than sending 10 million.

If your partner has an API that accepts 50 events at a time and you need to send 10 million events, you may be in trouble, unless that API can handle massive parallelism (or the data doesn’t need to get there for quite a while). On the flip side, you don’t need to be able to ingest one million events per second from your endpoint if the actual load is going to be miniscule.

By talking to customers ahead of time and understanding their use cases, we managed to learn a lot about how to build our cohort sync feature. We wanted to offer hourly cohort syncing with Braze, and some of our customers expected to sync cohorts of up to 10 million users. Knowing that our customers wanted to sync cohorts of that scale, we worked to speed up the process by a factor of 50. Now, cohorts of that size can export in just a few minutes.

Prioritize long-term roadmaps ahead of quick hacks

When building an integration, it’s tempting to figure out the quickest possible way to get it out the door. And while I agree that shipping fast is generally king, it’s important to remember that there are two companies involved with any integration, and generally a lot of coordination penalties. If your integration is built on top of a system that will soon be deprecated, it’s usually a good idea to wait until the replacement is rolled out and fully tested. Otherwise, you will build the integration, get people to start using it, and scramble to fix things when the integration inevitably breaks.

Recently, when we were working with a partner on a two-way integration, we realized that there were soon going to be major changes to the APIs we intended to use for the outbound integration. We could build the integration immediately, but then we would have to rewrite everything in short order. Fortunately, the inbound integration was much higher priority, so we decided to focus on that in the short-term.

Build on top of public APIs

Private APIs are a good thing, because they mean you are getting something special that no one else has…right? That may be true, but you are also getting something that’s less well supported. If you build atop a public API, you are using a (hopefully) supported system that is externally facing. If you build atop a private API, you are probably using something that one engineer hacked together in 2 days, and no one really knows how it works any more. If you need an enhancement to a public API, you can probably get it on that team’s development roadmap (assuming that the integration is important to them). If you need an enhancement to a private API, well, you are at their mercy (assuming they can decipher the code for the original integration).

So the next time that a partner wants to provide you with a private API (or really use anything that isn’t documented publicly on their website), try to get them to add it to their public APIs.

Start simple and iterate

Before you start building, you should clearly define ways to measure success of your integration. It could be setting metrics like “get N customers to use it over the first 3 months,” or “get X% usage increase in Y feature” — the important thing is that these metrics relate directly to business goals that you care about. Instrumentation for these metrics needs to be in place when the feature launches; otherwise you won’t know which integrations you should build 2.0 versions for and you’ll end up trying to cobble together bad proxies for the data that you really want.

Once you know what to measure, you can build out your minimum valuable product (MVP) to enable the use case.

It may be tempting to build everything possible into the initial version of an integration. But because it’s hard to know what customers are going to use, it’s better to start simple with the minimum, and then build more if people actually use it. For example, we built manual cohort sync and then came back to build scheduled syncing when a lot of people were already using it.

For various reasons, integrations with some partners will be more popular than others, so you’ll want to make sure you put your resources into the integrations that see the most usage. For example, we started out by building fairly simple integrations with three different marketing automation platforms. It turned out that our most popular marketing automation integration had over 10X the usage of the next most popular option. Now, when we build enhancements to our integrations, we start with that one first.

Summing it up

In order to build a good integration, you need to think about what you want it to accomplish and to make sure that it is designed and built soundly. A well-built integration can make both products better, while a poor one can confuse users and distract them from getting value. If both sides are clear on the value proposition, and you build something that empowers people to use your products better, the integration will be a net win for everyone.