How to build a unified API for your product integrations

A complete guide to building your own unified API for product integrations, including when to use them and step-by-step implementation.

Table of contents

Example H2

Building integrations with multiple third-party APIs can quickly become a maintenance nightmare. Each API has its own authentication flow, data models, rate limits, and quirks. As your product grows and you need to support more integrations, you might find yourself drowning in API-specific code.

This is where unified APIs come in. A unified API gives you a single, consistent interface for interacting with many different APIs. Instead of writing separate code for Salesforce, HubSpot, and Pipedrive, you write code once and it works across all of them.

But here's the thing: while pre-built unified APIs like Merge.dev can get you started quickly, most B2B SaaS companies eventually need to build their own custom unified APIs to support their specific use cases and data models.

In this guide, we'll walk you through everything you need to know about building unified APIs for your product integrations, from when to use them to step-by-step implementation.

Why unified APIs?

Done right, unified APIs can accelerate your integrations development, reduce maintenance overhead, and improve the developer experience for your team.

Advantages of unified APIs

Here are the key benefits of building a unified API for your product integrations:

Single interface simplifies code in your app
Instead of having different code paths for each API, you write integration logic once and it works across all supported platforms.
Faster to add support for new APIs
Once you have the unified model and infrastructure in place, adding a new API often just requires implementing the mapping layer.
Logic about API-specific mapping is centralized
All the complex logic for handling different API schemas, field mappings, and edge cases lives in one place, making it easier to maintain and debug.
Easier to apply customer-specific configuration
You can handle custom field mappings, filtering rules, and other customer-specific logic in a centralized way.
Consistent error handling and retry logic
You can implement robust error handling, rate limiting, and retry mechanisms once and apply them consistently across all integrations.

Drawbacks of unified APIs

However, unified APIs aren't without their challenges:

Unification = lowest common denominator
Your unified model can only include features that all external APIs support. This means you might miss out on powerful, API-specific capabilities.
Fields in the data model are often optional
To account for different coverage across APIs, many fields become optional, which still requires if-else statements in your application code.
Concepts don't always map perfectly
Different APIs use different terminology and data structures. For example, some APIs have separate "Contacts" and "Accounts" while others have "Leads," "Customers," and "Companies." This requires interpretation and mapping that can be complex.
Maintenance overhead for mapping logic
You need to maintain the mapping between each external API and your unified model, which can become complex as APIs evolve.

As noted in the Nango documentation on unified APIs, "Not all use cases and APIs are good fits for unification. You might need to leverage specific capabilities of an API that are impossible to standardize with others."

When is a unified API a good fit?

Not all integrations are equally important to your business. The decision to use a unified API should be based on your specific use case and customer needs.

Good fits for unified APIs

Unified APIs work well when:

You want to support the same core functionality across multiple APIs within a category
The APIs you're integrating with have similar data models and capabilities
You're building integrations for secondary or tertiary use cases (not your core differentiator)
You need to support many APIs but don't need deep, API-specific functionality

Poor fits for unified APIs

Avoid unified APIs when:

You're integrating with key systems where you want to leverage API-specific functionality
Most of your customers use one primary API (e.g., 80% use Salesforce)
The APIs have fundamentally different data models or capabilities
You need real-time or very specific functionality that varies significantly between APIs

Pre-built vs. custom unified APIs

When building unified APIs, you have two main options:

Pre-built unified APIs

These are built by external vendors for specific categories (e.g., CRM, accounting, HR). Examples include Merge.dev, Apideck, and Unified.to.

Pros:

Quick to implement
No need to build mapping logic yourself
Handles API changes and updates

Cons:

Limited by the vendor's data model
No ability to customize for your specific needs
Vendor lock-in
May not cover all the APIs you need
Limited visibility into how integrations work

Custom unified APIs

These are unified APIs built specifically for your product's integrations.

Pros:

You define the data model to match your needs
Full control over which APIs to support and how
Can evolve with your product requirements
No vendor lock-in
Better tradeoff between flexibility and implementation simplicity

Cons:

More upfront development work
You need to maintain the mapping logic
Responsibility for handling API changes

For most growing B2B SaaS companies, custom unified APIs offer the best balance of flexibility and maintainability.

How to build a unified API

Building a unified API is a significant undertaking, but following a structured approach will help you succeed. Here's our recommended process:

Step 1: Define the interactions with external APIs

Start with one category of integrations (e.g., CRMs, accounting systems, or project management tools). For each integration, make a list of every interaction you need with the external API:

Read data XYZ: initial sync on first connect, then fetch latest data every X minutes
Create ABC in the external system whenever D occurs in your app
Update records when they change in your system
Handle webhooks for real-time updates
Support custom field mappings

For each interaction, identify which external APIs you plan to support and verify that they actually support the functionality you need. You can use AI tools like Claude or Cursor to quickly check API documentation and confirm support for specific endpoints and data fields.

Step 2: Define your data model

For each interaction, define the data models you want to read and write. The key is to create a model that represents the data in a way that makes sense for your product.

Best practices for your unified data model:

Start with your existing data model
If your product already has a data model for the entities you're working with (e.g., contacts, companies, invoices), use this as your universal model. This ensures consistency with your application and includes all fields needed for your specific use case.
Simplify if needed
If your internal model is large, focus on the subset of fields that are most important to your customers. You can always extend it later.
Expect fields to be optional
Not all APIs will provide the same information. Design your logic to handle missing fields gracefully and build fallback mechanisms where necessary.
Use the same model for reads and writes
Adopt the same data model for both reading data (syncing) and writing data back to the API. This eliminates duplicate logic and makes your codebase cleaner.

Step 3: Implement for one external API

Focus on one API and implement the interactions with it end-to-end before moving on. This approach helps you:

Validate your data model
Identify edge cases and challenges
Build a working foundation
Create patterns that can be reused for other APIs

For your first implementation, you'll need to handle:

API Authentication
OAuth flows, API keys, or other authentication mechanisms
Data Syncing
Initial sync and ongoing incremental updates
Data Writing
Creating and updating records in the external system
Error Handling
Retry logic, rate limiting, and error recovery
Observability
Logging, monitoring, and debugging capabilities

As you implement, consider these important factors:

Cardinality differences (one customer may have 100 records, another 1M records)
Update frequency and real-time requirements
Webhook handling for real-time updates
Reconnection flows if authentication breaks
Data validation and schema enforcement

Step 4: Implement for additional external APIs

Once you have a working implementation for one API, implement additional APIs using the same patterns. This typically gets faster with each API as you:

Reuse authentication and infrastructure code
Apply the same error handling and retry logic
Use similar data mapping patterns
Leverage the same monitoring and observability tools

For each new API, focus on:

Mapping the API's data model to your unified model
Handling API-specific quirks and limitations
Implementing any unique authentication flows
Testing edge cases and error scenarios

Tools and frameworks to consider

Building a unified API is complex, but the right tools can significantly accelerate development and improve reliability:

AI-powered development tools

Claude Code or Cursor
Use AI to help with data mapping, API exploration, and code generation. These tools can quickly analyze API documentation and suggest mapping strategies.

Integration infrastructure platforms

Nango
Nango provides first-class support for building unified APIs with built-in authentication, data syncing, webhook handling, and observability. It's designed specifically for this use case and includes features like custom data validation.
Custom infrastructure
You can build your own infrastructure, but this requires significant engineering resources for authentication, syncing, monitoring, and error handling.

Data validation and schema management

Data validation library
Use a data validation library to enforce validation rules close to the external API source. This helps catch errors early and ensures your unified model remains reliable. Popular options include:
- Zod (TypeScript)
- Pydantic (Python)
- go-playground/validator (Go)
JSON Schema
For API documentation and validation across different programming languages.

When to consider pre-built solutions

Before building your own unified API, evaluate pre-built unified API vendors to see if they entirely cover your use case. However, be aware of potential limitations:

Vendor lock-in
Limited coverage with no ability to extend
Dependency on their support for debugging issues
Fixed data models that may not fit your needs

Best practices for unified API development

Based on our experience helping hundreds of companies build product integrations, here are some key best practices:

Design for extensibility

Build your unified API with the expectation that you'll need to add new APIs and modify existing ones. Use patterns that make it easy to:

Add new API providers
Modify data mappings
Handle API-specific edge cases
Support custom fields and configurations

Implement robust error handling

Different APIs have different error patterns and rate limits. Your unified API should:

Handle rate limiting gracefully with exponential backoff
Provide meaningful error messages
Log errors with sufficient context for debugging
Support retry mechanisms for transient failures

Build comprehensive observability

You need visibility into what's happening across all your integrations:

Detailed logging for all API interactions
Metrics on sync performance and error rates
Alerting for critical failures
Dashboards for monitoring integration health

Plan for data consistency

Unified APIs can introduce data consistency challenges:

Handle partial syncs and failures gracefully
Implement idempotency for write operations
Support conflict resolution strategies
Provide data validation and cleanup tools

Conclusion

Building a unified API for your product integrations is a significant undertaking, but it can provide substantial benefits in terms of development speed, maintainability, and consistency. The key is to approach it thoughtfully:

Start with a clear understanding of your use cases and data requirements
Build incrementally, starting with one API and expanding from there
Use tools and frameworks that accelerate development and improve reliability
Design for the long term with extensibility and maintainability in mind

Remember that unified APIs aren't always the right solution. For your most important integrations or when you need deep, API-specific functionality, consider building direct integrations instead. Use unified APIs for secondary integrations or when you need to support many APIs with similar core functionality.

The goal is to find the right balance between development speed and functionality that serves your customers' needs while keeping your engineering team productive and your codebase maintainable.

Build your unified API with Nango

First-class support for custom unified APIs with built-in infrastructure