Skip to content

Commit

Permalink
docs: improvements to What is Nango page (#3085)
Browse files Browse the repository at this point in the history 
<!-- Describe the problem and your solution --> 

<!-- Issue ticket number and link (if applicable) -->

<!-- Testing instructions (skip if just adding/editing providers) -->
  • Loading branch information
@bastienbeurier
bastienbeurier authored Dec 2, 2024
1 parent fa56a6e commit db7f268
Showing 1 changed file with 112 additions and 93 deletions.
205 changes: 112 additions & 93 deletions docs-v2/what-is-nango.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
---
title: 'What is Nango?'
sidebarTitle: 'What is Nango?'
description: 'Nango is product integration infrastructure for developers.'
description: 'Nango is the most powerful product integrations platform for developers.'
---

Nango is product **integration infrastructure for developers**. It helps you build, manage, and scale integrations with third-party APIs, through a single interface.

# Demo video

<div style={{ position: 'relative', overflow: 'hidden', paddingTop: '56.25%' }}>
<iframe
style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }}
Expand All @@ -19,110 +15,133 @@ Nango is product **integration infrastructure for developers**. It helps you bui
></iframe>
</div>

# Nango overview

Nango provides a unified interface to work with 250+ APIs, abstracting away the complexities of each API. This allows you to focus on building your product, rather than dealing with the intricacies of each API.

Nango differs from traditional unified APIs & embedded iPaaS as it is designed to be developer-first, with unlimited customization capabilities, offering a alternative to building and maintaining integrations in-house. It is meant to never constrain the integrations you can build, while providing a unified interface to work with different APIs.

Nango offers a suite of tools & services to help you build integrations faster, including:
- Pre-built integrations with 250+ APIs
- Developer tooling to build custom integrations with a unfied interface
- A service of API experts who can advise and build integrations for you


# Overview of integrating Nango
# Nango Overview

<Frame caption="The steps to integrate Nango.">
<img src="/images/integrate-nango.png" />
</Frame>
Nango is the **most powerful product integrations platform** designed for developers at B2B SaaS companies.

## 1. Get user permission in your app
Nango helps you build, manage, and scale integrations with third-party APIs, through a single interface. It is as flexible as building integrations in-house, while taking care of API-specific complexities for you, so you can focus on making integrations your best product feature.

Use the Nango frontend SDK to get the user's permission to access their external data.
With Nango you get:

Nango guides the user through the (O)Auth flow in a popup window.
**Hundreds of pre-built integrations**
- Ready-to-use integration templates for 250+ APIs

Store the `connectionId` & `integrationId` in your database to retrieve the user's data later.
**Developer tooling pre-configured for each API**
- Authorization: OAuth, API key, basic, custom
- Rate-limit handling, pagination and retries
- Two-way sync infrastructure
- End-to-end type safety and runtime data validation
- Real-time webhook infrastructure
- Observability and alerting: HTTP requests, customer-level reporting, etc
- Per-customer integration configuration: field mappings, toggle features, etc
- Tooling to develop, test, deploy, and migrate custom integrations (git-based)
- API unification with your own schemas
- UI components to embed in your app

```ts Frontend: Trigger the OAuth flow.
const nango = new Nango({ connectSessionToken });

// Shows authorization popup to the user.
await nango.openConnectUI({
onEvent: (event) {
if (event.type === 'connect') {
// The auth flow succeeded. The user is connected!
saveToDatabase(connectionId, integrationId);
}
}
});
```
**Comprehensive API documentation**
- Hundreds of API quirks, gotchas, helpful links, and hard-earned learnings

<Tip>
When a new user connects your integration, Nango automatically starts fetching their data (e.g. issues, contacts, files, etc.) in the background.
</Tip>
**Access to API experts**
- Experts for enterprise APIs (Netsuite, Workday, Salesforce, SAP, etc.)
- Sandbox accounts
- Service to build your custom integrations

## 2. Receive data update notifications
### How is Nango different from unified APIs and embedded iPaaS?

Nango uses webhooks to notify your backend when external user data has been added, updated or deleted. Nango will only alert you when there are actual changes.
Nango is built to replace building integrations in-house—offering the same flexibility and control, but faster and with less maintenance overhead. It is strictly developer-first, designed to support any API and empower developers to create exactly the integrations their customers need.

```json Backend: Webhook payload with new data
{
"connectionId": "user123",
"providerConfigKey": "zendesk",
"model": "ticket",
"responseResults": { "added": 2, "updated": 6, "deleted": 0 },
"modifiedAfter": "2023-05-31T11:46:13.390Z"
}
```
Unified APIs and embedded iPaaS tools take a more rigid approach, focusing on pre-built use cases that limit what you can build. Embedded iPaaS lack key abstractions developers rely on, like end-to-end type safety and API unification. Unified APIs, meanwhile, are locked into predefined schemas and use cases, making them a point solution at best.

## 3. Collect and save the new data
Nango is built with a different mindset: **to unleash integration creativity.** By providing best-in-class developer tooling tailored to each API, Nango removes limitations and empowers developers to create integrations that stand out—whether through deep customization, polished experiences, or handling the unique quirks of external APIs.

When you receive the webhook, fetch the most recent data from Nango using the backend SDK or API.
For a full comparison, read [How is Nango different from embedded iPaaS and Unified APIs?](https://www.nango.dev/blog/how-is-nango-different-from-embedded-ipaas-or-unified-api)

Nango returns the data in the schema of your choice, which can be standardized across different APIs.

You can directly save this data to your database, or process it further, as needed.

```ts Backend: Fetch & save new records.
const records = await nango.listRecords<Ticket>({
providerConfigKey: 'zendesk',
connectionId: 'user123',
model: 'ticket',
modifiedAfter: modifiedAfter
});

saveToDatabase(records);
```

## 4. Write back to external APIs

Push updates back to external APIs in a way that is:

- **Synchronous:** Have your changes immediately reflected.
- **Unified:** Benefit from standardized schemas across different APIs.
- **Customizable:** Support intricate workflows and composed API calls.
# Overview of integrating Nango

```ts Backend: Write back to external APIs.
const result = await nango.triggerAction({
providerConfigKey: 'zendesk',
connectionId: 'user123',
action: 'create-ticket',
input: { "title": "...", "content": "..." }
});
```
<Frame caption="The steps to integrate Nango.">
<img src="/images/integrate-nango.png" />
</Frame>

## 5. Customize integrations
<Steps>
<Step title="Get user permission in your app">
Use the Nango frontend SDK to get the user's permission to access their external data.

Nango lets you create custom integrations through code. Your custom integration code is then deployed and run by Nango, similarly to lambda functions:
Nango guides the user through the auth flow in a popup window.

<Frame>
<img src="/images/custom-scripts.png" />
</Frame>
Store the `connectionId` in your database to retrieve the user's data later.

Nango offers developer tooling to make custom integrations easier to build and maintain, abstracting API specificities into a unified interface to work with pagination, rate limits, and other API quirks.
```ts Frontend: Trigger the OAuth flow.
const nango = new Nango({ connectSessionToken });

<Tip>
**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>
// Shows authorization popup to the user.
await nango.openConnectUI({
onEvent: (event) {
if (event.type === 'connect') {
// The auth flow succeeded. The user is connected!
saveToDatabase(connectionId, integrationId);
}
}
});
```

<Tip>
When a new user connects your integration, Nango automatically starts fetching their data (e.g. issues, contacts, files, etc.) in the background.
</Tip>
</Step>
<Step title="Receive data update notifications">
Nango uses webhooks to notify your backend when external user data has been added, updated or deleted. Nango will only notify you when there are actual changes.

```json Backend: Webhook payload with new data
{
"connectionId": "user123",
"providerConfigKey": "zendesk",
"model": "ticket",
"responseResults": { "added": 2, "updated": 6, "deleted": 0 },
"modifiedAfter": "2023-05-31T11:46:13.390Z"
}
```
</Step>
<Step title="Collect and save the new data">
When you receive a Nango webhook, fetch the most recent data from Nango using the backend SDK or API.

Nango returns the data in the schema of your choice, which can be standardized across different APIs.

You can directly save this data to your database, or process it further, as needed.

```ts Backend: Fetch & save new records.
const records = await nango.listRecords<Ticket>({
providerConfigKey: 'zendesk',
connectionId: 'user123',
model: 'ticket',
modifiedAfter: modifiedAfter
});

saveToDatabase(records);
```
</Step>
<Step title="Write back to external APIs">
Push updates back to external APIs in a way that is:

- **Synchronous:** Have your changes immediately reflected.
- **Unified:** Benefit from standardized schemas across different APIs.
- **Customizable:** Support intricate workflows and composed API calls.

```ts Backend: Write back to external APIs.
const result = await nango.triggerAction({
providerConfigKey: 'zendesk',
connectionId: 'user123',
action: 'create-ticket',
input: { "title": "...", "content": "..." }
});
```
</Step>
<Step title="Customize integrations">
Nango stands out in its ability to let you create custom integrations through code.

Your custom integration code is deployed and run by Nango, similarly to lambda functions.

<Tip>
**Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>
</Step>
</Steps>

0 comments on commit db7f268

Please sign in to comment.