A unified software programming interface (API) is an API that serves as a layer of abstraction that may talk with a number of underlying APIs concurrently.
Consequently, every object and endpoint within the unified API maps to a corresponding object and endpoint within the underlying API. This allows SaaS firms to construct a single integration with the unified API and immediately ship integrations with every of the underlying APIs.
On this article, we are going to dive deep into unified APIs, how they work, their challenges and options, and the way they profit SaaS firms.
What drawback do unified APIs remedy?
SaaS patrons have come to count on seamless native integrations from the options they buy. Interoperability is now not a pleasant to have however a requirement. Nevertheless, constructing these native integrations with their different instruments is a problem each SaaS firm faces right this moment, because it requires important engineering assets to ship and preserve.
For each integration, engineers should construct safe authentication, comb by means of the third-party app’s API documentation, implement the enterprise logic required to ship the use case and construct an intuitive configuration expertise for the tip consumer.
And this doesn’t account for all of the work concerned in sustaining and updating the mixing as new function requests are added, when the third-party API releases breaking modifications, and the time builders spend serving to clients debug integration points.
Throughout the context of SaaS integrations, unified APIs emerged lately as a option to sort out the problem of understanding every third-party app’s API documentation.
At its core, this could save engineering groups from always studying or revisiting the nuances, shapes, and nomenclature for each particular person API, as soon as for each integration.
How do unified APIs work?
Let’s stroll by means of how a unified API works with a tangible instance.
Think about your clients are asking on your product to combine with their CRM – throughout your consumer base, some clients use Salesforce, others use HubSpot, and a few use Dynamics or Pipedrive.
A unified CRM API would summary the APIs of every of those CRMs by sustaining references to every of the underlying CRMs’ APIs.
Supply: Paragon
The instance right here exhibits that every underlying CRM has an object that represents a “contact.”
HubSpot calls it a Contact, Salesforce gives each a Lead and a Contact object, and Pipedrive refers to contacts as Prospects. When a name is made to the “Contact” object throughout the unified API, the unified API will then reference the corresponding object within the specified service.
Now, object-level references are the primary layer, however inside these objects, there are additionally properties or fields which can be abstracted. Within the instance above, that would embody totally different nomenclature for title, ID, firm, and so on.
So, in case your workforce is constructing a number of CRM integrations, theoretically, you’ll be able to construct a single integration with a unified CRM API that lets you ship all of the underlying CRM integrations concurrently.
Class-specific unified APIs
Not all APIs may be unified in a single API as a result of totally different SaaS purposes have distinctive knowledge fashions, buildings, and options.
Due to this fact, distributors sometimes supply a number of unified APIs which can be particular to a sure SaaS vertical, corresponding to CRM, accounting, or promoting, as these SaaS purposes can have comparatively related knowledge buildings and share many frequent objects or properties.
When designing a unified API, the API supplier should fastidiously select which underlying APIs to incorporate within the unified API, because the extra overlap the underlying APIs have, the broader the protection the unified API can present.
Nevertheless, if the unified API had been to incorporate purposes that aren’t as related to one another, it might be much less helpful because it would not have the ability to floor all of the objects and properties that the underlying APIs share. For example, a unified API that features a CRM and an accounting software might not be very helpful as a result of outdoors of a “buyer” object, there might not be a lot overlap throughout the remainder of the purposes’ knowledge fashions.
What are the advantages of unified APIs?
Unified APIs present a number of advantages to engineering groups that have to ship and preserve dozens of integrations.
API abstractions
As an alternative of studying and interacting with the person APIs of every service, your engineering workforce solely must learn to interface with the unified API as soon as (per class).
This not solely makes constructing these integrations simpler and quicker but in addition helps scale back the complexity of integrations.
Moreover, with regards to upkeep, the unified API vendor is chargeable for dealing with the communication with the underlying APIs, which implies your workforce does not want to fret about breaking modifications being made to one of many underlying APIs. Finally, the unified API vendor will probably be chargeable for updating their abstraction to make sure the mixing continues to work.
Managed authentication
Unified API suppliers typically supply a managed authentication service that abstracts away the complexities of authentication with the underlying APIs, whether or not it’s through API keys or OAuth.
Whenever you combine with a number of APIs instantly, you must handle the authentication course of for every one, together with managing consumer credentials and making certain safe token refresh insurance policies.
On condition that there are various nuances in how every software handles authentication, this generally is a cumbersome and error-prone process, particularly in case you’re working with a lot of APIs.
Logging
By nature, the unified API makes proxy requests to its underlying APIs. As such, they are going to accumulate and analyze knowledge concerning the requests made to the third-party purposes. Consequently, when a request fails, the unified API supplier can log this occasion and supply particulars on the error message that was returned by the underlying API.
This logging performance may be helpful on your workforce because it permits them to establish points which may be occurring with their integrations rapidly. Slightly than going by means of the logs from a number of third-party APIs, they’ll depend on the unified API supplier to centralize the logging and error reporting.
With debugging errors, unified API suppliers can usually present extra detailed error messages than the underlying APIs themselves. It’s because they’ll analyze the error response and supply extra context across the root reason behind the difficulty, which may drastically scale back the period of time spent on diagnosing errors and velocity up incident response instances.
Pre-built consumer interface
Most unified API suppliers present a pre-built interface on your clients to authenticate into an integration, saving you from constructing the configuration expertise your self.
This offloads your workforce from designing the consumer expertise for every integration, which may compound when it comes to time financial savings when contemplating the handfuls of potential integrations you’ll be able to construct on the unified API.
What are the challenges with utilizing unified APIs?
Whereas unified APIs present the advantages shared above, they’re crippled by some structural limitations that firms are beginning to develop into extra conscious of.
Use case limitations
On condition that unified APIs can solely summary the “shared” objects and endpoints amongst the underlying APIs, you’ll be able to solely construct options which can be comparatively easy and generalizable throughout all of the integrations. That is by far the most important limitation of any unified API answer.
Moreover, the extra purposes supported inside a unified API, the extra restricted it turns into.
Supply: Paragon
Let’s stroll by means of some examples of those limitations.
Irreconcilable options
If you must construct an integration function that entails performance or properties which can be particular to one of many integrations, that won’t be attainable with a unified API.
For instance, let’s say that you just wish to combine with a number of buyer suggestions instruments through a “unified suggestions API.” If one instrument leverages a quantitative mannequin with suggestions scores between 1-10, whereas one other solely collects “damaging, impartial, optimistic” accompanied by “notes,” there isn’t any method {that a} unified API can assist these use instances, as you can not reconcile these right into a single reference.
Lacking fields
If the property you must replace through the mixing is just out there for a selected subset of the supported integrations, that property gained’t be made out there throughout the unified API.
For instance, even when a number of of the underlying third-party purposes have ZIP code as a subject, so long as one doesn’t, ZIP code cannot be accessed as a property through the unified API.
Customized objects and fields
By nature, unified APIs present a set of pre-defined references to every underlying API. Nevertheless, in case you introduce customized objects or fields into the combination, the unified API supplier can not anticipate what these objects or fields are. Due to this fact, they can’t assist integrations that contain customized objects or fields.
This generally is a large blocker in case your clients require the integrations you present to assist the usage of customized objects throughout the third-party purposes.
Fee limits
If you end up integrating with a number of APIs directly through a unified API, you want to pay attention to the speed limits of every API and be certain that your integration logic does not exceed the bounds for anyone API.
Which means that the logic you construct should adhere to the speed limits of the API with the bottom threshold for price limits. Put merely, the API with the bottom price restrict would be the limiting issue on your integration. In case you attempt to make too many requests to that API’s endpoints, your requests will begin to fail, even when the opposite APIs within the unified API can technically assist that very same quantity.
To keep away from hitting price restrict errors when making bulk requests to particular endpoints for these integrations, you need to use batching or throttling to manage the speed of requests you ship to every API.
So, whereas it’s nonetheless attainable to work round decrease price limits, you’ll end up constructing extra complexity into your codebase to be able to accommodate limitations from any one of many underlying integrations.
Safety
Unified APIs typically require that you just authorize entry to all scopes for a third-party service to be able to use their API, versus permitting you to pick particular person scopes for every integration.
Which means that whenever you authenticate a consumer to make use of your integration, the consumer will probably be compelled to offer you entry to all the knowledge related to that third-party service, not simply the info required for the mixing.
For example, you’re constructing a CRM integration through a unified API, and the CRM has entry to gross sales, advertising and marketing, and buyer assist knowledge. When a consumer authenticates their account to make use of your integration, you’d be given entry to all three units of information, even when all of your software wants is the gross sales knowledge.
This may elevate safety considerations on your clients. To mitigate these considerations, it is essential to be clear together with your customers about what knowledge you might be requesting entry to and to elucidate why you want that knowledge clearly.
Moreover, provided that the seller typically hosts unified APIs, you’re counting on the seller to make sure that they’ve robust safety measures in place to guard your customers’ knowledge from unauthorized entry or breaches.
Opinionated knowledge mannequin
How the seller reconciles totally different underlying APIs and reference endpoints is topic to their very own opinion. Whereas this isn’t an issue for many use instances, there will probably be instances when they could current an abstraction that you just disagree with, or that doesn’t adhere to the anticipated conduct.
Roadmap constraints
In comparison with embedded integration platforms, which give one-on-one abstractions of each third-party API throughout many classes, unified API distributors are restricted to the classes for which they’ve constructed unified APIs.
Whereas they’ll and can construct new unified APIs over time, in case you ask for an integration with a class that’s not at the moment supported, likelihood is you’ll have to attend years for that integration to be made out there.
The one exception could be if the seller occurred to be constructing out a unified API for the class that the requested integration matches into. Nonetheless, given the breadth of the SaaS ecosystem and the potential classes they might assist, this may not often be the case.
Workarounds: There are positively numerous limitations that include unified APIs, which may make you assume twice concerning the true worth of unified APIs; the distributors that exist right this moment are attempting to give you distinctive options to supply workarounds.
For instance, sure suppliers created the power to make “pass-through” requests to the underlying API. Nevertheless, right this moment’s implementation continues to be very limiting and creates a subpar developer expertise.
When do you have to use a unified API
In the case of deciding whether or not a unified API is the appropriate answer on your workforce, you’ll be able to observe easy decision-making standards.
Standards
If all the following are true, then it’s definitely price evaluating.
- Your integration roadmap is restricted to the classes supported by the unified API supplier.
- Each integration use case you’ll ever have to construct may be generalized throughout each software within the class.
- You’ll be able to make investments devoted assets to constructing an infrastructure that may deal with the amount of requests required to assist your clients as you scale.
- You don’t want your assist workforce to have visibility into how the mixing behaves and the place it errored out, and you’ll have the engineering workforce bounce in to debug.
In case you can’t confidently say sure to the 4 factors above, it’s possible you’ll not wish to be locked into utilizing a unified API.
As an alternative, an embedded integration platform could also be a greater answer, as they permit you to construct a lot deeper integrations whereas offering extra complete tooling to assist streamline the mixing growth course of.
The B2B SaaS integration problem
Deciding on an answer that will help you scale your SaaS product’s native integration roadmap shouldn’t be a straightforward one. You not solely have to make sure that it may possibly handle your use instances right this moment but in addition all attainable use instances your clients might request sooner or later.
Unified APIs generally is a nice answer for delivery dozens of integrations with minimal effort, offered that the use instances your clients require are uniform throughout each integration inside a given class.
It’s a growing market with many new gamers and is definitely an fascinating strategy to fixing the B2B SaaS integration problem.
Study all about APIs, their advantages, challenges, and use instances within the complete information.
