Crafting Integrations with Nango
Working on integrations with Nango? You’re in luck! A whopping 95% of the work is already done for you. Nango provides all the intricate infrastructure required for integrations (feature list).
All that’s left for you is to code the remaining 5% that is unique to your integration:
- What data do you want to sync?
- How should this data be transformed? What should be the final data model?
- What data do you need to write back and when?
With this, Nango creates a fully-typed SDK and ensures your integrations run seamlessly in production.
Understanding the Architecture
Users can authorize integrations within your app via an OAuth popup. This is as simple as making a call to the frontend SDK.
Nango handles the acquisition, storage, and refreshing of API credentials.
Nango enables you to specify how data syncs with external APIs, for instance, fetching Salesforce contacts or Google Calendar events. You define these syncs, and they live in your repository, version-controlled along with the rest of your codebase.
Once your syncs are ready, you deploy them to Nango via a CLI command. Nango then takes over, running them in production, handling scaling, scheduling, retries, data caching, de-duplication, and more.
Continuous Sync Architecture
There might be times when you want to make one-off API requests, for instance:
- Writing data back on an as-needed basis
- Fetching data that doesn’t need continuous syncing (e.g., for onboarding)
The Proxy simplifies this process, offering benefits such as authorization, retries, rate-limit handling, and monitoring.
For examples and more details, check out the Proxy guide.
Nango supports two kinds of webhooks:
- External webhooks: these go from the external API to Nango, notifying of data changes in real-time
- Nango webhooks: these go from Nango to your app, notifying your app that new data is available (upon sync job completion or external webhook reception)
To learn more, refer to the Webhooks guide
Dashboard: Sync Monitoring & Management
The Nango Dashboard provides a detailed activity log for every sync and proxy request. Here, you can view comprehensive logs of every sync run and even log your messages from sync scripts.
Furthermore, you can view and manage the syncs for each connection (integration setup by a user).
Frequently used terms:
An API configuration (like the
hubspot configuration) holds the specific Nango configuration for an external API. This includes:
- Auth-related configuration (auth type, OAuth URLs, auth quirks, etc.)
- Sync-related configuration (rate-limits, pagination strategy, etc.)
These configurations, contributed and regularly improved by Nango and its community, enable rapid adaptation of Nango to work with any API via editing a
.yaml configuration file.
For more information and to contribute API configurations, click here.
Developers create integrations, based on API configurations, to work with external APIs from their app.
Integrations are created by you in the Nango Dashboard. You then control how they work with syncs and our SDKs or REST APIs.
When a user of your app authorizes an integration, Nango calls this a new connection: E.g.
user1 authorizes a
Github integration to sync issues in your app.
Connections represent the relation between an end user and an external API. It contains the necessary credentials to access the external API on behalf of the user together with metadata and per-user configuration.
Syncs are responsible to continuously synchronize data between an external API and Nango. Each sync has:
- an entry in the
nango.yamlconfiguration file in the
- a sync file (typescript script) in the
nango-integrationsfolder Syncs have ‘runs’ or ‘jobs’ that are executed periodically. They can be managed (stopped, paused, resync, etc.) from the Dashboard or your code (with the SDK/REST API).