Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: API docs page outline #3093

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

docs: API docs page outline #3093

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2da23b8
Example API page
bastienbeurier Nov 28, 2024
74e7ee8
New edits based on feedback
bastienbeurier Dec 2, 2024
c4e569a
Add example of empty states
bastienbeurier Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 127 additions & 16 deletions docs-v2/integrations/all/hubspot.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,140 @@ title: HubSpot
sidebarTitle: HubSpot
---

API configuration: [`hubspot`](https://nango.dev/providers.yaml)
## Overview

## Features
<CardGroup cols={3}>
<Card title="Pre-built tooling" icon="screwdriver-wrench" href="#pre-built-tooling"/>
<Card title="Pre-built use-cases" icon="square-check" href="#pre-built-use-cases"/>
<Card title="Access requirements" icon="triangle-exclamation" href="#access-requirements"/>
<Card title="Setup guide" icon="rocket" href="#setup-guide"/>
<Card title="Useful links" icon="circle-info" href="#useful-links"/>
<Card title="API gotchas" icon="biohazard" href="#api-gotchas"/>
</CardGroup>

| Features | Status |
| - | - |
| [Auth (OAuth)](/guides/getting-started/authorize-an-api-from-your-app) | ✅ |
| [Sync data](/guides/getting-started/read-from-an-api) | ✅ |
| [Perform workflows](/guides/getting-started/write-to-an-api) | ✅ |
| [Proxy requests](/guides/proxy-requests-to-an-api) | ✅ |
| [Receive webhooks](/guides/receive-webhooks-from-an-api) | ✅ |
## Pre-built tooling

<Tip>We can implement missing features in &lt;48h, just ask for it in the [community](https://nango.dev/slack).</Tip>
<AccordionGroup>
<Accordion title="✅ Authorization">
| Tools | Status |
| - | - |
| Pre-built authorization (OAuth 2) | ✅ |
| Credentials auto-refresh | ✅ |
| Auth parameters validation | Not needed |
| Credentials validation | Not needed for OAuth |
| Pre-built Connect UI | ✅ |
| Custom authorization UI | ✅ |
| End-user authorization guide | Not needed for OAuth |
| Expired credentials detection | ✅ |
</Accordion>
<Accordion title="✅ Read & write data">
| Tools | Status |
| - | - |
| Pre-built use-cases | ✅ |
| API unification | ✅ |
| 2-way sync | ✅ |
| Webhooks from Nango on data modifications | ✅ |
| Real-time webhooks from 3rd-party API | ✅ |
| Proxy requests | ✅ |
</Accordion>
<Accordion title="✅ Observability & data quality">
| Tools | Status |
| - | - |
| HTTP request logging | ✅ |
| End-to-type type safety | ✅ |
| Data runtime validation | ✅ |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bastienbeurier Since we mention some platform level features here, IMO we could add:

  • OpenTelemetry export
  • Slack Alerts on errors
  • Integration status API

| OpenTelemetry export | ✅ |
| Slack alerts on errors | ✅ |
| Integration status API | ✅ |
</Accordion>
<Accordion title="✅ Customization">
| Tools | Status |
| - | - |
| Create or customize use-cases | ✅ |
| Pre-configured pagination | ✅ |
| Pre-configured rate-limit handling | ✅ |
| Per-customer configurations | ✅ |
</Accordion>
</AccordionGroup>

## Getting started
## Pre-built use-cases

- [How to register an Application](https://developers.hubspot.com/docs/api/working-with-oauth#initiating-an-integration-with-oauth-2-0)
- [OAuth-related docs](https://developers.hubspot.com/docs/api/oauth-quickstart-guide)
- [List of OAuth scopes](https://developers.hubspot.com/docs/api/working-with-oauth#scopes)
- [API](https://developers.hubspot.com/docs/api/overview)
<AccordionGroup>
<Accordion title="Companies">
| Endpoint | Description | Readme |
| - | - | - |
| `GET /companies` | Fetches a list of companies from Hubspot | [🔗](https://github.com/NangoHQ/integration-templates/blob/main/integrations/hubspot/syncs/companies.ts)|
| `POST /companies` | Creates a single company in Hubspot | [🔗](https://github.com/NangoHQ/integration-templates/blob/main/integrations/hubspot/syncs/companies.ts)|
| `PATCH /companies` | Update a single company in Hubspot | [🔗](https://github.com/NangoHQ/integration-templates/blob/main/integrations/hubspot/syncs/companies.ts)|
| `DEL /companies` | Deletes a company in Hubspot | [🔗](https://github.com/NangoHQ/integration-templates/blob/main/integrations/hubspot/syncs/companies.ts)|
</Accordion>
<Accordion title="Contacts"></Accordion>
<Accordion title="Deals"></Accordion>
<Accordion title="Owners"></Accordion>
<Accordion title="Pipelines"></Accordion>
<Accordion title="Products"></Accordion>
<Accordion title="Properties"></Accordion>
<Accordion title="Roles"></Accordion>
<Accordion title="Tasks"></Accordion>
<Accordion title="Others"></Accordion>
</AccordionGroup>

<Tip>Not seeing the use-case you need? [Build your own](https://nango.dev/slack) independently.</Tip>

## Access Requirements

| Pre-Requisites | Status | Comment|
| - | - | - |
| Paid dev account | ✅ Not required | Free, self-signup [here](https://developers.hubspot.com/). |
| Paid test account | ✅ Not required | Create free Enterprise account for testing from your developer account. |
| Partnership | ✅ Not required | |
| App review | ✅ Not required | Only required for marketplace listing, not for integration distribution. |
| Security audit | ✅ Not required | |

## Setup guide

<Steps>
<Step title="Create a developer account">
Go to [Hubspot's developer signup page](https://app.hubspot.com/signup-hubspot/developers) and create an account.
</Step>
<Step title="Create & configure a Hubspot app">
Start creating a Hubspot app by clicking on the _Create app_ button.

In the _Auth_ tab, configure the following Redirect URL: `https://api.nango.dev/oauth/callback`.

Create the Hubspot app. In the _Auth_ tab, copy/paste the `Client ID` and `Client secret`, you will need to specify it in Nango later on.
</Step>
<Step title="Set up the OAuth scopes">
Still in the _Auth_ tab, add the scopes that are relevant to how you want to consume the Hubspot API. Copy/paste the list of scopes, you will need to specify it in Nango later on.
</Step>
<Step title="Create a Hubspot test account">
If you don't have a Hubspot account already, create one to test your integration.
</Step>
<Step title="Next">
Follow the [_Getting Started_ guides](/guides/getting-started).
</Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

## Useful links

| Topic | Links |
| - | - |
| General | [Website](https://www.hubspot.com/) |
| | [Create a test account](https://app.hubspot.com/signup-hubspot/crm) |
| Developer | [API documentation](https://developers.hubspot.com/beta-docs/reference/api/overview) |
| | [Create a developer account](https://app.hubspot.com/signup-hubspot/developers) |
| | [Developer console](https://app.hubspot.com/) |
| | [Authorization documentation](https://developers.hubspot.com/docs/api/oauth-quickstart-guide) |
| | [Register an OAuth app](https://developers.hubspot.com/docs/api/working-with-oauth#initiating-an-integration-with-oauth-2-0) |
| | [List of OAuth scopes](https://developers.hubspot.com/docs/api/working-with-oauth#scopes) |
| | [Details on rate limits](https://developers.hubspot.com/beta-docs/guides/apps/api-usage/usage-details) |

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/insightly.mdx)</Note>

## API gotchas

<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/hubspot.mdx)</Note>
_No reported gotchas yet_

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/hubspot.mdx)</Note>
107 changes: 86 additions & 21 deletions docs-v2/integrations/all/insightly.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,100 @@ title: Insightly
sidebarTitle: Insightly
---

API configuration: [`insightly`](https://nango.dev/providers.yaml)
## Overview

## Features
<CardGroup cols={3}>
<Card title="Pre-built tooling" icon="screwdriver-wrench" href="#pre-built-tooling"/>
<Card title="Pre-built use-cases" icon="square-check" href="#pre-built-use-cases"/>
<Card title="Access requirements" icon="triangle-exclamation" href="#access-requirements"/>
<Card title="Setup guide" icon="rocket" href="#setup-guide"/>
<Card title="Useful links" icon="circle-info" href="#useful-links"/>
<Card title="API gotchas" icon="biohazard" href="#api-gotchas"/>
</CardGroup>

| Features | Status |
| - | - |
| [Auth (Basic)](/guides/getting-started/authorize-an-api-from-your-app) | ✅ |
| [Sync data](/guides/getting-started/read-from-an-api) | ✅ |
| [Perform workflows](/guides/getting-started/write-to-an-api) | ✅ |
| [Proxy requests](/guides/proxy-requests-to-an-api) | ✅ |
| [Receive webhooks](/guides/receive-webhooks-from-an-api) | 🚫 (time to contribute: &lt;48h) |
## Pre-built tooling

<Tip>We can implement missing features in &lt;48h, just ask for it in the [community](https://nango.dev/slack).</Tip>
<AccordionGroup>
<Accordion title="✅ Authorization">
| Tools | Status |
| - | - |
| Pre-built authorization ([FILL-IN-PROGRAMMATICALLY:OAuth|API Key|Basic]) | ✅ |
| Credentials auto-refresh | ✅ |
| Auth parameters validation | ✅ |
| Credentials validation | ✅ |
| Pre-built Connect UI | ✅ |
| Custom authorization UI | ✅ |
| End-user authorization guide | ✅ |
| Expired credentials detection | ✅ |
</Accordion>
<Accordion title="✅ Read & write data">
| Tools | Status |
| - | - |
| Pre-built use-cases | ([FILL-IN-PROGRAMMATICALLY:✅|🚫 (time to contribute: &lt;48h)]) |
| API unification | ✅ |
| 2-way sync | ✅ |
| Webhooks from Nango on data modifications | ✅ |
| Real-time webhooks from 3rd-party API | ✅ |
| Proxy requests | ✅ |
</Accordion>
<Accordion title="✅ Observability & data quality">
| Tools | Status |
| - | - |
| HTTP request logging | ✅ |
| End-to-type type safety | ✅ |
| Data runtime validation | ✅ |
| OpenTelemetry export | ✅ |
| Slack alerts on errors | ✅ |
| Integration status API | ✅ |
</Accordion>
<Accordion title="✅ Customization">
| Tools | Status |
| - | - |
| Create or customize use-cases | ✅ |
| Pre-configured pagination | ✅ |
| Pre-configured rate-limit handling | ✅ |
| Per-customer configurations | ✅ |
</Accordion>
</AccordionGroup>

## Getting started
## Pre-built use-cases

- [Insightly basic auth related docs](https://api.na1.insightly.com/v3.1/#!/Overview/Introduction)
- [Insightly API docs](https://api.na1.insightly.com/v3.1)
- [API Versions](https://api.na1.insightly.com/v3.1/#!/Overview/Introduction)
- [API rate limits](https://api.na1.insightly.com/v3.1/#!/Overview/Technical_Details)
[FILL-IN-PROGRAMMATICALLY-SIMILARLY-TO-HUBSPOT]

Empty state: _No pre-built use-cases yet (time to contribute: &lt;48h)._

<Tip>Not seeing the use-case you need? [Build your own](https://nango.dev/slack) independently.</Tip>

## Access Requirements

| Pre-Requisites | Status | Comment|
| - | - | - |
| Paid dev account | ❓ | |
| Paid test account | ❓ | |
| Partnership | ❓ | |
| App review | ❓ | |
| Security audit | ❓ | |

## Setup guide

Empty state: _No setup guide yet._

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

<Note>Contribute improvements to the setup guide by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/insightly.mdx)</Note>

## Useful links

[FILL-IN-PROGRAMMATICALLY-BASED-ON-EXISTING-LINKS-WITH-A-FORMAT-SIMILAR-TO-HUBSPOT]

Empty state: _No useful links yet._

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/insightly.mdx)</Note>

## API gotchas

- Insightly uses `Basic` auth mode to access different endpoints. Provide your `api key` as your username and leave the password field empty.
- Your instances `pod` can be determined by accessing `User Settings` and finding the API URL right under your API Key in the API Section. This connection config will be set when creating a new connection on Nango i.e: If this is your API URL ; `https://api.na1.insightly.com/v3.1/` add `na1` as your pod connection config.
- Insightly still supports older API versions, but they have fewer endpoints. To use a specific version of the API append it to your `base_url` as follows: `/v3.1/Contacts` or `/v3.0/Contacts`.
- Depending on the pricing plan, there are various rate limits. Once your limit is reached, you will no longer be able to make requests against that endpoint until next day.
- You can have a look at the following [Nango](https://docs.nango.dev/guides/customize/handle-rate-limits) resource to see how best you can handle rate limits.
[FILL-IN-PROGRAMMATICALLY-BASED-ON-EXISTING-GOTCHAS-WITH-A-FORMAT-SIMILAR-TO-HUBSPOT]

Empty state: _No API gotchas yet._

<Note>Add Getting Started links and Gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/insightly.mdx)</Note>
<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs-v2/integrations/all/hubspot.mdx)</Note>
Loading