Five Tips for Building Better SaaS Product Integrations

If you're a SaaS company, building product integrations is critical. This has been covered enough already. No need to hammer it home.

This post is easy going...just a straight up "five tips" listicle to help you build better product integrations. No further introduction is necessary.

Here we go...

Use Case First, Not API First

Typically a product integration (or any integration for that matter) is about mapping how how data flows from one API to the other. In the case of a product integration, one of those APIs is your product's API and the other is a tech partner's.

When tasked with building a new product integration, the first inclination tends to be to go straight to the tech partner's API documentation. Of course it're building an API integration.


You will eventually get to inspecting the tech partner's API. You will eventually get to aligning their API endpoints and data model to yours to design out how data can flow between those APIs smoothly. However, this is not the best place to start.

Remember: A product integration is not about providing data integration between two software products. It's about enabling your tech partner's and your mutual users with a cross-product experience that makes them better at their jobs. You want your tech partner's product and yours to behave, in some way, as if they are one to provide value for those mutual users.

This means the place you should actually start is at the use case level, not the API

Define what that cross-product experience looks like in a format that looks more like an Agile user story than it does a data mapping table or a process design diagram. Here's a helpful formula:

When <something happens> in <one of the systems>, <persona> wants to <something that should happen> in <the other system> so I can <why that's valuable>.

This is a modified version of "job story" format, an alternative to traditional Agile user stories. This is not the only way to define a use case, but it's a pretty easy way that fits the need. It makes you think about who benefits from the integration and ties it back to what it's actually doing to change their daily life. It helps you to define the cross-product experience before designing the integration.

A product integration may be as simple as one job story. It may be more complex. When you have many job stories and a limited budget or timeline, that list now becomes an easy-to-negotiate set of features that all stakeholders in the business can prioritize.

Exception: It is actually OK to start with the API docs.

When it comes to generally scoping and providing a high level estimate for an integration project, you do actually kind of need to start with the API documentation. You shouldn't be designing yet, but you should look to check on a few key things:

  • Is there an API available?
  • What type of API is it? REST? HTTP, but not REST? SOAP Web Services? Something else?
  • What authentication methods are available? How do you get tokens or permission?
  • How well documented is the API? Do you see examples and well written descriptions of end points?
  • Does it generally look to have the entities you'll need to integrate with?
  • Anything else about it look unique or difficult?

You'll get into the weeds on this much later, but when you're triaging and guesstimating, you'll need to gather the basic info. In this case, it's ok if you start with the tech partner's API documentation.

Write as little code as possible.

Building integrations is usually cumbersome. Complex ones can be really cumbersome. Writing, testing, and maintaining code is too!

Fundamentally you do need some software written in code that can move data between API endpoints. After all, that is what an integration is. However, when building product integrations, your team would be wise to write as  little code as possible.

What are some things you can do to accomplish this?

  • Use a prebuilt integration framework or product. Don't reinvent how to build integrations. Others have written that code before.
  • Look for reuse whenever possible. If you build an integration for the first customer to X product, but X product has hundreds more potential integration users, think about building the integration as a reusable template. Don't build new every time unless users have very unique requirements.
  • Elevate user-specific logic to configuration, ideally configuration that they provide. Only codify what works for everyone.

Code is expensive. That's why software engineers are expensive. If the only method you have with providing your end users with integrations is to code them, then you're probably missing out on better ways to accomplish this.

Integration platforms-as-a-service are designed to replace or reduce coding for integrations. Many of them now offer (or are dedicated to) embedded features which allow you to white label their capabilities into your product. This can be a great option if you have the budget for an iPaaS and are willing to put your users in someone else's hands.

Open source integration frameworks, like Open Integration Hub, also help by reducing the code you have to write to enable an integration capability. In this case, you take more ownership, but you don't pay a licensing fee.

Figure out how to minimize the coding being used in your integration program, and those projects will start going faster and easier.

This post dives into some of these options in more detail.

Use the 80-20 Rule.

The 80-20 rule as it applies to integration projects is as follows: 80% of your time is going to be spent figuring out how to implement 20% of your integration requirements. That's also likely where the end user is going to derive 80% of the value from the integration.

Building integration isn't hard, until it gets hard. Then it gets really hard really fast. The 80-20 rule helps to give you some guidance for where you should focus your energy at design time. The goal here is to avoid letting the "really hard" part create a bad experience for your users.

Product integrations are more complex than a standard integration project, because it introduces a second stakeholder. When you are designing the integration the obvious stakeholder exists: the team on the other side who has a product with an API. However, there's also a second stakeholder: the end user of their and your product who needs to use the integration.

That means you have two phases of "doing stuff" to get the integration live. First you have to design/build it. Then you have to configure it for a user.

That configuration might be super easy. It might just be providing a couple of API tokens and everything else is hardcoded. Likely, it's somewhere more challenging than that. The more complex or flexible the integration, the higher the burden is for aligning user requirements to what can be configured in the integration.

If you got that wrong in design time--if the templated integration you built can't meet significant needs for end users--their experience getting the thing up and running will be poor. It might not work at all. It might lose you a paying user.

That 20% of requirements that takes 80% of your time is likely where you'll find those problems that can lose users. Shine a bright light on that part of your product integration design process. Involve users, ideally before a mission critical implementation project. Reduce risk.

You can't find every possible pitfall, but you can work ahead, eliminating a bunch of them.

Plan for failure.

Building an integration that works correctly on the happy path is not that hard, relatively speaking. Almost any software engineer can do that. Building an integration that handles failure gracefully is significantly harder. The latter is the difference between a skunkworks integration project and a sophisticated, stable integration approach.

Building an integration that supports a cross-product experience for your user means you are building something that, to them, is mission critical. If you and your technology partner have convinced your mutual user to automate or otherwise streamline some part of their job on top of your integration, then you better be sure it's going to do its job.

Failure (in the user's eyes) is not an option.

However, failure is inevitable, and it's your responsibility as the creator and maintainer of that integration to shoulder this burden.

APIs fail. Data gets dropped. People mistype information. Servers go down. Network connectivity gets unstable. This stuff just happens, and any of it can cause an integration to stop working for quick blips or long periods of time.

When designing your integrations and the framework upon which you build them consider the following:

  • How do you detect failures ASAP and alert appropriate parties?
  • What happens then? How do you clean up lost data or missed transactions?
  • How do you proactively monitor for things that are likely to cause problems?
  • What's your failover plan?
  • How do you leverage your customer success teams to add a personal touch when an integration get troublesome?

Planning for a dealing with inevitable errors, failures, and mishaps with an integration is such an important and often overlooked part of building product integrations. Make sure a significant part of the conversation is about reliability and contingency planning.

Plan for success.

It's also important that you prepare for success. What happens if your integrations become well adopted? Are you ready for that?

Integrations that support low data volumes for a few number of people are much easier to support and require much less computing power than high volumes and lots of users. Obviously integration adoption is the goal, so are you prepared for what happens when you get what you want?

This is another place an iPaaS or a properly architected integration framework becomes extremely valuable. It's critical that you build integrations on infrastructure that can scale elastically to meet demand. You should be looking at or asking about integration capabilities built on technologies like Docker containers, Kubernetes, and serverless technologies. These are modern infrastructure approaches that allow you to scale without necessarily rebuilding.

Adoption happens fast, and the last thing you want to do is halt everything so you can rethink the integration architecture.

Your customers don't care about integrations, they care about their cross-product experience. That means, they definitely don't care about the fact that you coded something that doesn't scale.

Expect to succeed. Plan to succeed. Leverage underlying technology that will support that success.

faster. easier. more cost-effective.
We can help you deliver more integrations faster, increasing revenue opportunity and reducing cost. Let's talk about how.
start the conversation