A unified application programming interface (API) is an API that serves as a layer of abstraction that can communicate with multiple underlying APIs simultaneously.
As a result, each object and endpoint in the unified API maps to a corresponding object and endpoint in the underlying API. This enables SaaS companies to build a single integration with the unified API and instantly ship integrations with each of the underlying APIs.
In this article, we will dive deep into unified APIs, how they work, their challenges and features, and how they benefit SaaS companies.
SaaS buyers have come to expect seamless native integrations from the solutions they purchase. Interoperability is no longer a nice to have but a requirement. However, building these native integrations with their other tools is a challenge every SaaS company faces today, as it requires significant engineering resources to ship and maintain.
For every integration, engineers must build secure authentication, comb through the third-party app’s API documentation, implement the business logic required to deliver the use case and build an intuitive configuration experience for the end user.
And this does not account for all the work involved in maintaining and updating the integration as new feature requests are added, when the third-party API releases breaking changes, and the time developers spend helping customers debug integration issues.
Within the context of SaaS integrations, unified APIs emerged in recent years as a way to tackle the challenge of understanding each third-party app’s API documentation.
At its core, this should save engineering teams from constantly learning or revisiting the nuances, shapes, and nomenclature for every individual API, once for every integration.
Let’s walk through how a unified API works with a tangible example.
Imagine your customers are asking for your product to integrate with their CRM - across your user base, some customers use Salesforce, others use HubSpot, and some use Dynamics or Pipedrive.
A unified CRM API would abstract the APIs of each of these CRMs by maintaining references to each of the underlying CRMs’ APIs.
Source: Paragon
The example here shows that each underlying CRM has an object that represents a “contact.”
HubSpot calls it a Contact, Salesforce provides both a Lead and a Contact object, and Pipedrive refers to contacts as Prospects. When a call is made to the “Contact” object within the unified API, the unified API will then reference the corresponding object in the specified service.
Now, object-level references are the first layer, but within those objects, there are also properties or fields that are abstracted. In the example above, that could include different nomenclature for name, ID, company, etc.
So, if your team is building multiple CRM integrations, theoretically, you can build a single integration with a unified CRM API that enables you to ship all the underlying CRM integrations simultaneously.
Not all APIs can be unified in a single API because different SaaS applications have unique data models, structures, and features.
Therefore, vendors typically offer multiple unified APIs that are specific to a certain SaaS vertical, such as CRM, accounting, or advertising, as these SaaS applications will have relatively similar data structures and share many common objects or properties.
When designing a unified API, the API provider must carefully choose which underlying APIs to include in the unified API, as the more overlap the underlying APIs have, the wider the coverage the unified API can provide.
However, if the unified API were to include applications that aren’t as similar to each other, it would be less useful as it wouldn't be able to surface all the objects and properties that the underlying APIs share. For instance, a unified API that includes a CRM and an accounting application may not be very useful because outside of a “customer” object, there may not be much overlap across the rest of the applications’ data models.
Unified APIs provide multiple benefits to engineering teams that need to ship and maintain dozens of integrations.
Instead of learning and interacting with the individual APIs of each service, your engineering team only needs to learn how to interface with the unified API once (per category).
This not only makes building these integrations easier and faster but also helps reduce the complexity of integrations.
Additionally, when it comes to maintenance, the unified API vendor is responsible for handling the communication with the underlying APIs, which means your team doesn't need to worry about breaking changes being made to one of the underlying APIs. Ultimately, the unified API vendor will be responsible for updating their abstraction to ensure the integration continues to work.
Unified API providers generally offer a managed authentication service that abstracts away the complexities of authentication with the underlying APIs, whether it be via API keys or OAuth.
When you integrate with multiple APIs directly, you have to manage the authentication process for each one, including managing user credentials and ensuring secure token refresh policies.
Given that there are many nuances in how each application handles authentication, this can be a cumbersome and error-prone task, especially if you're working with a large number of APIs.
By nature, the unified API makes proxy requests to its underlying APIs. As such, they will collect and analyze data about the requests made to the third-party applications. As a result, when a request fails, the unified API provider can log this event and provide details on the error message that was returned by the underlying API.
This logging functionality can be useful for your team as it allows them to identify issues that may be occurring with their integrations quickly. Rather than going through the logs from multiple third-party APIs, they can rely on the unified API provider to centralize the logging and error reporting.
With debugging errors, unified API providers can often provide more detailed error messages than the underlying APIs themselves. This is because they can analyze the error response and provide more context around the root cause of the issue, which can greatly reduce the amount of time spent on diagnosing errors and speed up incident response times.
Most unified API providers provide a pre-built interface for your customers to authenticate into an integration, saving you from building the configuration experience yourself.
This offloads your team from designing the user experience for each integration, which can compound in terms of time savings when considering the dozens of potential integrations you can build on the unified API.
While unified APIs provide the benefits shared above, they are crippled by some structural limitations that companies are starting to become more aware of.
Given that unified APIs can only abstract the “shared” objects and endpoints amongst the underlying APIs, you can only build features that are relatively simple and generalizable across all the integrations. This is by far the biggest limitation of any unified API solution.
Additionally, the more applications supported within a unified API, the more limited it becomes.
Source: Paragon
Let’s walk through some examples of these limitations.
If you need to build an integration feature that involves functionality or properties that are specific to one of the integrations, that will not be possible with a unified API.
For example, let’s say that you want to integrate with multiple customer feedback tools via a “unified feedback API.” If one tool leverages a quantitative model with feedback scores between 1-10, whereas another only collects “negative, neutral, positive” accompanied by “notes,” there is no way that a unified API can support those use cases, as you cannot reconcile those into a single reference.
If the property you need to update via the integration is only available for a specific subset of the supported integrations, that property won’t be made available within the unified API.
For example, even if a few of the underlying third-party applications have ZIP code as a field, as long as one does not, ZIP code can not be accessed as a property via the unified API.
By nature, unified APIs provide a set of pre-defined references to each underlying API. However, if you introduce custom objects or fields into the mix, the unified API provider cannot anticipate what those objects or fields are. Therefore, they cannot support integrations that involve custom objects or fields.
This can be a huge blocker if your customers require the integrations you provide to support the use of custom objects within the third-party applications.
When you are integrating with multiple APIs at once via a unified API, you need to be aware of the rate limits of each API and ensure that your integration logic doesn't exceed the limits for any one API.
This means that the logic you build must adhere to the rate limits of the API with the lowest threshold for rate limits. Put simply, the API with the lowest rate limit will be the limiting factor for your integration. If you try to make too many requests to that API's endpoints, your requests will start to fail, even if the other APIs in the unified API can technically support that same volume.
To avoid hitting rate limit errors when making bulk requests to specific endpoints for those integrations, you must use batching or throttling to control the rate of requests you send to each API.
So, while it is still possible to work around lower rate limits, you’ll find yourself building additional complexity into your codebase in order to accommodate limitations from any one of the underlying integrations.
Unified APIs generally require that you authorize access to all scopes for a third-party service in order to use their API, as opposed to allowing you to select individual scopes for each integration.
This means that when you authenticate a user to use your integration, the user will be forced to give you access to all of the data associated with that third-party service, not just the data required for the integration.
As an example, you’re building a CRM integration via a unified API, and the CRM has access to sales, marketing, and customer support data. When a user authenticates their account to use your integration, you would be given access to all three sets of data, even if all your application needs is the sales data.
This can raise security concerns for your customers. To mitigate these concerns, it's important to be transparent with your users about what data you are requesting access to and to explain why you need that data clearly.
Additionally, given that the vendor generally hosts unified APIs, you’re relying on the vendor to ensure that they have strong security measures in place to protect your users' data from unauthorized access or breaches.
How the vendor reconciles different underlying APIs and reference endpoints is subject to their own opinion. While this is not a problem for most use cases, there will be times when they may present an abstraction that you disagree with, or that does not adhere to the expected behavior.
Compared to embedded integration platforms, which provide one-on-one abstractions of every third-party API across many categories, unified API vendors are restricted to the categories for which they’ve built unified APIs.
While they can and will build new unified APIs over time, if you ask for an integration with a category that is not currently supported, chances are you’ll have to wait years for that integration to be made available.
The only exception would be if the vendor happened to be building out a unified API for the category that the requested integration fits into. Still, given the breadth of the SaaS ecosystem and the potential categories they could support, this will rarely be the case.
Workarounds: There are definitely a lot of limitations that come with unified APIs, which can make you think twice about the true value of unified APIs; the vendors that exist today are trying to come up with unique solutions to provide workarounds.
For example, certain providers created the ability to make “pass-through” requests to the underlying API. However, today's implementation is still very limiting and creates a subpar developer experience.
When it comes to deciding whether a unified API is the right solution for your team, you can follow simple decision-making criteria.
If all of the following are true, then it’s certainly worth evaluating.
If you can’t confidently say yes to the four points above, you may not want to be locked into using a unified API.
Instead, an embedded integration platform may be a better solution, as they enable you to build much deeper integrations while providing more comprehensive tooling to help streamline the integration development process.
Deciding on a solution to help you scale your SaaS product’s native integration roadmap is not an easy one. You not only have to ensure that it can address your use cases today but also all possible use cases your customers may request in the future.
Unified APIs can be a great solution for shipping dozens of integrations with minimal effort, provided that the use cases your customers require are uniform across every integration within a given category.
It is a developing market with many new players and is certainly an interesting approach to solving the B2B SaaS integration challenge.
Learn all about APIs, their benefits, challenges, and use cases in the comprehensive guide.
The future of SaaS lies in embedded ecosystems.
by Sara Du
Tired of the complex and endless cycle of integrations and reintegrations? Are they standing...
by Daniel Twigg
You know that feeling when you're talking to your customer, and things are going really well?
by Sharjeel Ahmed
