.svg){kind=small}
How Unified APIs work
A Unified API is an aggregation and abstraction layer on top of multiple underlying APIs. In addition to this aggregation, Unified APIs play several additional roles such as normalizing data across each underlying API, providing features to manage the integration lifecycle, and running infrastructure to sync data to and from each API.
5 key aspects of a Unified API
Unified APIs aggregate data from multiple supported integrations, normalize that data across integrations, manage authentication and authorization, consistently access that data via API, and sync the data continuously.
We'll walk through the following five key aspects of how a Unified API works:
- Aggregation: Scope of data and integrations supported
- Normalization: How data is mapped across each integration
- Authentication and authorization: How integrations are set up
- Access: How data is retrieved from the Unified API
- Syncing: How the Unified API keeps data up-to-date
Aggregation: How categories and integrations are scoped
Unified APIs are built around software systems of record where there is an industry standard of data definitions and structures. CRM systems, for example, have commonly followed standards for Contacts, Accounts, and Opportunities based on industry-defining products like Salesforce.
When developing a Unified API, architects will look for these systems of record and standard data structures to delineate what is and isn't included in the API. They look for consistency in data objects, fields, and relationships that make normalizing data predictable and useful.
Related: Examples of API aggregators
Normalization: How data models are defined
Data normalization is crucial when working with multiple integrations. Each customer will have their chosen integration, and in some cases their own configuration of data in each integration. Data from each of these integrations is normalized by a Unified API in the following scenarios:
Fields have different data types
For example, a short integer in one API may be a string in another.
Fields have different enums or picklists
For example, country names or currencies have common meanings but different representations in different APIs.
Required parameters differ
In particular when POSTing or PATCHing data, required parameters are essential for making a successful API request. For example, recruiting candidate data objects may be structured to require a job application in some systems, but not in others.
Objects and fields have different relationships
Object hierarchies and associations vary across APIs and need to be structured in a standard way. For example, project management systems have tickets that can be nested in some APIs, while others may not support nesting of parent and child tickets.
Related: Common examples of unified APIs across software categories
Authentication and authorization: How users set up an integration
Unified APIs are embedded within software to make it easier for that software's users to add integrations. That means that setting up integrations, including both authentication and authorization, is a very important step to get right and to support at the scale of many hundreds or thousands of users.
Unified APIs prioritize easy developer experience and robust customer data controls in their authentication and authorization components. This makes it simple to offer the end user a menu of integration options, to collect the required authentication credentials, and to limit the scope of data that is accessed. It is a similar user experience to OAuth flows you may be familiar with when authorizing data in a consumer mobile app.
To work, a Unified API must be able to make API requests on behalf of a customer or user to a software provider.
Unified APIs include embeddable authentication components that collect a user's authentication credentials at the time they set up an integration. These credentials are stored as a token and used to make requests on behalf of the customer going forward.
Unified APIs also include authorization functionality, to scope or delimit which data is allowed to be accessed using their authentication credentials. This scope is stored with the user's authentication tokens.
Related: A guide to integrating multiple APIs
Access: How developers interact with endpoints, rate limits, and pagination
Unified APIs present one standardized API for interacting with many APIs of software providers. This standardization takes many forms, including a common set of:
API endpoints: Unified APIs present one set of endpoints to access rather than needing to interact with each API individually.
API request structure: These Unified API endpoints are typically built to conform to a REST model, whereas underlying APIs may have a variety of structures, including SOAP or GraphQL.
API response structure: Unified API endpoints maintain a standard response structure as well, typically using JSON as the response format. Again, underlying APIs vary and may use SOAP or other response formats.
API methods: Unified APIs standardize GET, POST, and PATCH methods to ensure that interacting with data can be accomplished with the same requests and responses, regardless of underlying API.
Pagination: Unified APIs apply a standard pagination, whereas underlying APIs may have a variety of pagination approaches, page sizes, and ordering.
Rate limiting: Unified APIs sync data with each underlying API according to each provider's rate limits so that you can consume data without needing to understand the differences between providers.
Error handling: Unified APIs apply a standard set of error codes and responses so you can easily distinguish issues that otherwise are handled differently by each underlying API.
Syncing: How data is refreshed
Unified APIs don't just normalize data structure and access methods, they also sync the data for you. This has some big implications, so let's run through how it works.
- Unified APIs make API requests on behalf of your customers for each of their configured integrations.
- Sync frequencies are defined for each data model and target system. A sync will also be triggered immediately on the integration being configured as well as when a resync is manually triggered.
- The Unified API diffs the data received with the prior state of the data to notify your app of changes and updates to the data.
- You access the newly updated data via the Unified API.
Once the data is synced, Unified APIs emit a webhook to your app so that you can take action, such as retrieving the data via the Unified API right away. This is incredibly powerful as it provides near real-time data updates without having to poll each target system or build webhooks with each system yourself.
With a Unified API syncing data on behalf of your users, you'll be able to tap into a constantly updated and clean set of data. You won't need to run infrastructure to do data polling or transform the data. This is a huge win for your engineering productivity and infrastructure budget. It does mean that Unified APIs store your users' data, so you'll want to select a Unified API that is reliable, secure, and a good data steward. Check out the Evaluation Guide on how to choose a Unified API that meets your data needs.
Additional Unified API Resources
If you're looking to go deeper on Unified APIs, check out these essential articles:
For all of this info in one comprehensive place, download the Guide to Unified APIs.
.jpg)
.png)
