Read more about the advantages and disadvantages of unified APIs here: How Nango thinks about unified APIs.

​
Best practices for API unification

Based on our experience helping hundreds of companies build product integrations, here are some best practices for unifying APIs effectively:

​
Unify with your 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 for API unification. This approach has several advantages:
  • It gives you a single, consistent model for your application
  • It ensures that the unified model contains all the fields needed for your specific use case
  • If your internal model is large, simplify it to focus on the subset of fields that are most important to your customers

​
Expect fields to be optional

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.

​
Use the same model for reads and writes

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.

​
Enforce custom data validation rules in your custom integrations

When building custom integrations in Nango, leverage Nango’s built-in support for data validation using the zod library. By enforcing validation rules in Nango functions, 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.

​
How to build a unified API in Nango

To build a custom unified API in Nango, follow these steps:

​
1. Define your unified model

Start by defining your unified model with a zod model in a file, e.g., models.ts.
models.ts
export const UserUnified = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

​
2. Define your unified endpoints

In your script’s configuration, standardize the configuration of endpoints across APIs for consistency: use the same method, path, and parameters across APIs. 
import { createAction } from 'nango';
import { UserUnified } from './models.js';

export default createAction({
  endpoint: {
    method: 'POST',
    path: '/users',
    group: 'Users',
  },
  input: UserUnified,
  output: UserUnified,
  exec: async (nango, input) => {
    // Create user in Jira
  }
});

​
3. Fetch data and transform

In your custom functions, implement data-fetching logic and apply necessary transformations to align external data with the unified model.

​
Optional enhancements

  • Enforce generated types in your codebase: Nango will leverage your unified model to generate strongly-typed interfaces for your codebase, reducing errors and improving developer productivity
  • Custom data validation: Leverage Nango’s integration with zod to define custom validation rules tailored to your unified model (More about data validation)
  • Runtime data validation: Nango includes built-in runtime validation, which surfaces warnings in the Logs tab of the Nango UI when runtime data validation errors are detected

​
Calling the unified API from your app

Once your unified API is ready, you can interact with it programmatically by making calls to the unified endpoints.

​
API specific features

When dealing with API-specific data or functionality, Nango provides tools to handle edge cases without breaking your unified model:
  • Extend common models: Extend your unified model to include custom adaptations for specific APIs (ref). This ensures flexibility while preserving standardization for the majority of your integrations
  • Add API-specific fields: Include additional fields that are unique to certain APIs when needed. This keeps the unified model clean while supporting specific API capabilities
  • Attach the raw external data: Store raw API responses in a dedicated field to give you maximum flexibility for debugging, advanced use cases, or special handling of certain integrations
Questions, problems, feedback? Please reach out in the Slack community.