Guide on how to unify API endpoints & models.
API unification is the process of standardizing multiple APIs with varying endpoints and schemas into a single, consistent interface for easier integration.
Unification is treated as a first-class citizen in Nango, but it is optional.
If you opt in for API unification, Nango lets you define your own unified endpoints and models so that they fit your specific use case.
However, when API unification becomes limiting, Nango preserves your ability to have integrations that fully leverage an API’s specific data and capabilities.
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. For example, Notion’s block-based structure reflects unique ways its API is consumed, making it difficult to unify with other knowledge management APIs like Google Drive or SharePoint. While basic use cases such as listing files or exporting plain-text documents can be unified, advanced capabilities like complex handling of Notion blocks cannot. APIs with no standard equivalent capabilities are sometimes referred to as unstructured APIs.
Even when APIs have standard models, such as CRMs (contacts, companies), accounting systems (transactions, invoices), or HR platforms (employees, teams) — often called structured APIs — unification can still be imperfect due to discrepancies across providers. For instance, an Applicant Tracking System (ATS) might have 5 candidate statuses, another 10, and a third might allow fully customizable statuses. Mapping these statuses into a single unified model requires decisions that cannot follow a “one-size-fits-all” approach. These decisions have significant consequences for how your integration functions and must account for different use cases. For SaaS companies, these decisions often need to adapt to the specific logic of each customer, especially if they use custom fields or statuses.
Fortunately, Nango streamlines this process while giving you full control over how you unify APIs to match your exact needs. It ensures flexibility to handle both standard models and specific API nuances without sacrificing functionality.
Most SaaS products integrate with core systems of record, such as CRMs, accounting platforms, HR systems, or support tools. These systems typically include models with shared capabilities and fields — for example, a support ticket will usually have a title, description, author, and status. Integrating with these systems often means covering multiple providers chosen by your customers, which is where API unification provides the most value. By unifying the external models into a common internal model, you encapsulate the per-API logic (fetching and mapping data) into clean, reusable components. This keeps your standard integration logic simple and focused on your product’s internal needs.
API unification doesn’t need to be perfect to deliver value. Even partial alignment across APIs is often sufficient. For example, you might unify most fields across multiple APIs but include special handling for certain APIs that support additional fields or lack certain data. While this reintroduces some per-API logic, it is far smaller and more manageable, particularly as integrations grow in number and complexity.
Based on our experience helping hundreds of companies build product integrations, here are some best practices for unifying APIs effectively:
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 for API unification. This approach has several advantages:
Not all APIs will provide the same information. Some fields in your unified model will inevitably be null
for certain APIs. Design your logic to handle missing fields gracefully, and build fallback mechanisms where necessary. This ensures that your integrations remain robust even when data is incomplete.
Adopt the same data model for both reading data (e.g., syncing) and writing data back to the API. This approach eliminates duplicate logic in your application and integrations, making your codebase cleaner and easier to maintain.
When building custom integrations in Nango, leverage Nango’s built-in support for data validation using the zod library (docs). By enforcing validation rules in Nango scripts, close to the external API source, you can catch errors early, reduce downstream bugs, and simplify debugging. Validations ensure that your unified model remains reliable and predictable across all integrated APIs.
Most of Nango’s integrations are not unified out of the box because one-size-fits-all unification often falls short of real-world requirements. Instead, we encourage you to focus on unifying APIs based on your specific use case.
In the future, we may introduce default unified models as examples or starting points, but the flexibility to customize remains key.
To build a custom unified API in Nango, follow these steps:
Start by defining your unified model in the nango.yaml
file. This is where you standardize the fields and structure for your use case:
In your nango.yaml
configuration, standardize the configuration of endpoints across APIs for consistency: use the same method, path & parameters across APIs.
In your custom scripts, implement data-fetching logic and apply necessary transformations to align external data with the unified model.
Once your unified API is ready, you can interact with it programmatically by making calls to the unified endpoints.
When dealing with API-specific data or functionality, Nango provides tools to handle edge cases without breaking your unified model:
If you need custom unified integrations tailored to your needs, you can hire Nango to handle the development. Our team also provide expertise to accelerate your integration development. Check out our services for details.
Questions, problems, feedback? Please reach out in the Slack community.
Guide on how to unify API endpoints & models.
API unification is the process of standardizing multiple APIs with varying endpoints and schemas into a single, consistent interface for easier integration.
Unification is treated as a first-class citizen in Nango, but it is optional.
If you opt in for API unification, Nango lets you define your own unified endpoints and models so that they fit your specific use case.
However, when API unification becomes limiting, Nango preserves your ability to have integrations that fully leverage an API’s specific data and capabilities.
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. For example, Notion’s block-based structure reflects unique ways its API is consumed, making it difficult to unify with other knowledge management APIs like Google Drive or SharePoint. While basic use cases such as listing files or exporting plain-text documents can be unified, advanced capabilities like complex handling of Notion blocks cannot. APIs with no standard equivalent capabilities are sometimes referred to as unstructured APIs.
Even when APIs have standard models, such as CRMs (contacts, companies), accounting systems (transactions, invoices), or HR platforms (employees, teams) — often called structured APIs — unification can still be imperfect due to discrepancies across providers. For instance, an Applicant Tracking System (ATS) might have 5 candidate statuses, another 10, and a third might allow fully customizable statuses. Mapping these statuses into a single unified model requires decisions that cannot follow a “one-size-fits-all” approach. These decisions have significant consequences for how your integration functions and must account for different use cases. For SaaS companies, these decisions often need to adapt to the specific logic of each customer, especially if they use custom fields or statuses.
Fortunately, Nango streamlines this process while giving you full control over how you unify APIs to match your exact needs. It ensures flexibility to handle both standard models and specific API nuances without sacrificing functionality.
Most SaaS products integrate with core systems of record, such as CRMs, accounting platforms, HR systems, or support tools. These systems typically include models with shared capabilities and fields — for example, a support ticket will usually have a title, description, author, and status. Integrating with these systems often means covering multiple providers chosen by your customers, which is where API unification provides the most value. By unifying the external models into a common internal model, you encapsulate the per-API logic (fetching and mapping data) into clean, reusable components. This keeps your standard integration logic simple and focused on your product’s internal needs.
API unification doesn’t need to be perfect to deliver value. Even partial alignment across APIs is often sufficient. For example, you might unify most fields across multiple APIs but include special handling for certain APIs that support additional fields or lack certain data. While this reintroduces some per-API logic, it is far smaller and more manageable, particularly as integrations grow in number and complexity.
Based on our experience helping hundreds of companies build product integrations, here are some best practices for unifying APIs effectively:
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 for API unification. This approach has several advantages:
Not all APIs will provide the same information. Some fields in your unified model will inevitably be null
for certain APIs. Design your logic to handle missing fields gracefully, and build fallback mechanisms where necessary. This ensures that your integrations remain robust even when data is incomplete.
Adopt the same data model for both reading data (e.g., syncing) and writing data back to the API. This approach eliminates duplicate logic in your application and integrations, making your codebase cleaner and easier to maintain.
When building custom integrations in Nango, leverage Nango’s built-in support for data validation using the zod library (docs). By enforcing validation rules in Nango scripts, close to the external API source, you can catch errors early, reduce downstream bugs, and simplify debugging. Validations ensure that your unified model remains reliable and predictable across all integrated APIs.
Most of Nango’s integrations are not unified out of the box because one-size-fits-all unification often falls short of real-world requirements. Instead, we encourage you to focus on unifying APIs based on your specific use case.
In the future, we may introduce default unified models as examples or starting points, but the flexibility to customize remains key.
To build a custom unified API in Nango, follow these steps:
Start by defining your unified model in the nango.yaml
file. This is where you standardize the fields and structure for your use case:
In your nango.yaml
configuration, standardize the configuration of endpoints across APIs for consistency: use the same method, path & parameters across APIs.
In your custom scripts, implement data-fetching logic and apply necessary transformations to align external data with the unified model.
Once your unified API is ready, you can interact with it programmatically by making calls to the unified endpoints.
When dealing with API-specific data or functionality, Nango provides tools to handle edge cases without breaking your unified model:
If you need custom unified integrations tailored to your needs, you can hire Nango to handle the development. Our team also provide expertise to accelerate your integration development. Check out our services for details.
Questions, problems, feedback? Please reach out in the Slack community.