diff --git a/docs-v2/pages/connect/api-proxy.mdx b/docs-v2/pages/connect/api-proxy.mdx index 654aeba7a5c04..c0e8e24779e0b 100644 --- a/docs-v2/pages/connect/api-proxy.mdx +++ b/docs-v2/pages/connect/api-proxy.mdx @@ -1,4 +1,3 @@ -import { Tabs } from 'nextra/components' import Callout from '@/components/Callout' # Connect API Proxy diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index a8f2d0c7a8cb6..f320df2e2145b 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -38,13 +38,68 @@ You can skip steps 1 and 2 if you already know the component you want to use or +### Authenticate to the Pipedream API + +Before sending requests to the API, make sure to [authenticate using a Pipedream OAuth client](/rest-api/auth#oauth): + + + +```javascript +// Initialize the Pipedream client with the SDK + +import { createBackendClient } from "@pipedream/sdk/server"; + +const pd = createBackendClient({ + environment: "development | production", + credentials: { + clientId: "{oauth_client_id}", + clientSecret: "{oauth_client_secret}", + }, + projectId: "{your_project_id}" +}); +``` + + +```bash +# Get an access token for the REST API + +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{your_oauth_client_id}", + "client_secret": "{your_oauth_client_secret}" + }' +``` + + + + +All subsequent examples assume that you've either initialized the SDK client or have a valid access token. + + ### Find the app you want to use -In order to find the right trigger or action to configure and run, you first need to find the app. In this example, we'll search for `gitlab`. +To find the right trigger or action to configure and run, first find the app. In this example, we'll search for `gitlab`. -```text -GET /v1/connect/apps?q=gitlab + + +```javascript +const apps = await pd.getApps({ q: "gitlab" }); + +// Parse and return the data you need +``` + + +```bash +curl -X https://api.pipedream.com/v1/apps?q=gitlab \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer {access_token}" + +# Parse and return the data you need ``` + + Here's the response: @@ -77,9 +132,25 @@ Here's the response: Once you have the app you want to use, now you can list the triggers and/or actions for that app. We'll list the actions for Gitlab and we'll pass the `name_slug` `gitlab` as the `app`. -```text -GET /actions?app=gitlab + + +```javascript +const components = await pd.getComponents({ q: "gitlab" }); + +// Parse and return the data you need ``` + + +```bash +curl -X https://api.pipedream.com/v1/connect/{project_id}/actions?app=gitlab \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: development" \ + -H "Authorization: Bearer {access_token}" + +# Parse and return the data you need +``` + + Here's the response: @@ -156,9 +227,25 @@ details. As an example, the following API call will return the structure of the **List Commits** action for Gitlab: -```text -GET /v1/connect/components/gitlab-list-commits + + +```javascript +const component = await pd.getComponent({ key: "gitlab-list-commits" }); + +// Parse and return the data you need +``` + + +```bash +curl -X https://api.pipedream.com/v1/connect/{project_id}/components/gitlab-list-commits \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: development" \ + -H "Authorization: Bearer {access_token}" + +# Parse and return the data you need ``` + + The response will contain the component's structure, including its user-friendly name, version, and most importantly, the configuration options the component accepts @@ -217,10 +304,6 @@ steps, focused on getting the right input parameters (aka Configuring each prop for a component often involves an API call to retrieve the possible values, unless the values that a prop can take are static or free-form. The endpoint is accessible at: -```text -POST /v1/connect/components/configure -``` - Typically, the options for a prop are linked to a specific user's account. Each of these props implements an `options` method that retrieves the necessary options from the third-party API, formats them, and sends them back in the @@ -232,31 +315,56 @@ The payload for the configuration API call must contain the following fields: 2. `id`: the component's unique ID (aka **key**) 3. `prop_name`: the name of the prop you want to configure 4. `configured_props`: an object containing the props that have already been - configured. The initial configuration call must contain the ID of the account - (aka `authProvisionId`) that your user has connected to the target app (see - [this section](workflows#configure-accounts-to-use-your-end-users-auth) for - more details on how to create these accounts). + configured. The initial configuration call must contain the ID of the account + (aka `authProvisionId`) that your user has connected to the target app (see + [this section](workflows#configure-accounts-to-use-your-end-users-auth) for + more details on how to create these accounts). We'll use the [**List Commits** component for Gitlab](https://github.com/PipedreamHQ/pipedream/blob/master/components/gitlab/actions/list-commits/list-commits.mjs#L4) as an example, to illustrate a call that retrieves the options for the -`projectId` prop of that component. The payload sent to the configuration API -would look like this: - -```json -{ - "external_user_id": "demo-34c13d13-a31e-4a3d-8b63-0ac954671095", - "id": "gitlab-list-commits", - "prop_name": "projectId", - "configured_props": { - "gitlab": { - "authProvisionId": "apn_oOhaBlD" +`projectId` prop of that component: + + + +```javascript +const { options } = await pd.configureComponent({ + externalUserId: "abc-123", + id: "gitlab-list-commits", + propName: "projectId", + configuredProps: { + gitlab: { + authProvisionId: "apn_kVh9AoD", } } -} +}); + +// Parse and return the data you need +``` + + +```bash +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/configure \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: development" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "external_user_id": "abc-123", + "id": "gitlab-list-commits", + "prop_name": "projectId", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_kVh9AoD" + } + } + }' +# Parse and return the data you need ``` + + + -The response will contain the possible values (and their human-readable labels +The response contains the possible values (and their human-readable labels when applicable) for the prop, as well as any possible errors that might have occurred. The response for the request above would look like this: @@ -348,7 +456,7 @@ The set of props that a component can accept might not be static, and may change depending on the values of prior props. Props that behave this way are called [dynamic props](/components/api#dynamic-props), and they need to be configured in a different way. Props that are dynamic will have a `reloadProps` attribute -set to `true` in the component's code. +set to `true` in the component's definition. After configuring a dynamic prop, the set of subsequent props must be recomputed (or reloaded), which is possible using the following API call: @@ -452,8 +560,8 @@ supports two types of components: [actions](/components#actions) and Actions are components that perform a task by taking an input either during [configuration](#configure-the-component) and/or during invocation (usually both), and -produce a result. Sources are very similar, but the difference is that they are -not invoked directly by Pipedream users, but rather by events that happen on a +produces a result. Sources are very similar, but the difference is that they are +not invoked directly by end users directly, but rather by events that happen on a third-party service. For example, the "New File" source for Google Drive will be triggered every time a new file is created in a specific folder in Google Drive, then will emit an event for you to consume. @@ -472,11 +580,11 @@ used for configuring a prop, with the exception of the `prop_name` attribute ```json { "async_handle": "xFfBakdTGTkI", - "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9", + "external_user_id": "abc-123", "id": "gitlab-list-commits", "configured_props": { "gitlab": { - "authProvisionId": "apn_JjhWOl0" + "authProvisionId": "apn_kVh9AoD" }, "projectId": 45672541, "refName": "main" @@ -487,9 +595,45 @@ used for configuring a prop, with the exception of the `prop_name` attribute To run the action with this configuration, simply send it as the request payload to the following endpoint: -```text -POST /v1/connect/actions/run + + +```javascript +const resp = await pd.runAction({ + externalUserId: "abc-123", + id: "gitlab-list-commits", + configuredProps: { + gitlab: { + authProvisionId: "apn_kVh9AoD", + }, + projectId: 45672541, + refName: "main" + } +}); + +// Parse and return the data you need +``` + + +```bash +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: development" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "external_user_id": "abc-123", + "id": "gitlab-list-commits", + "prop_name": "projectId", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_kVh9AoD" + } + } + }' + +# Parse and return the data you need ``` + + The output of executing the action will be a JSON object containing the following fields: @@ -532,21 +676,19 @@ above: #### Deploying a source -Because sources are exercised by events that happen on a third-party service, -their semantics are different from actions. Once a source is configured, it must -be deployed in order to start listening for events. You might be asking where do -those events go, and you'd be right to ask. That's the reason why when deploying -a source you must provide a URL where the source will send these events, similar -to how a webhook works. +Because sources are exercised by events that happen on a third-party service, +their semantics are different from actions. Once a source is configured, it must +be deployed to start listening for events. When deploying a source, you +can define either a webhook URL or a Pipedream workflow ID to consume those events. Deploying a source is done by sending a payload similar to the one used for -running an action, with the addition of the webhook URL mentioned above. Using +running an action, with the addition of the webhook URL or workflow ID. Using the **New Issue (Instant)** source for Gitlab as an example, the payload would look something like this: ```json { - "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9", + "external_user_id": "abc-123", "id": "gitlab-new-issue", "prop_name": "http", "configured_props": { @@ -559,11 +701,53 @@ look something like this: } ``` -The endpoint to deploy a source is: +Deploy a source for your users: + + + +```javascript +const { data: deployedTrigger } = await pd.deployTrigger({ + externalUserId: "abc-123", + id: "gitlab-new-issue", + propName: "projectId", + configuredProps: { + gitlab: { + authProvisionId: "apn_kVh9AoD", + } + }, + webhookUrl: "https://events.example.com/gitlab-new-issue" +}); -```text -POST /v1/connect/triggers/deploy +const { + id: triggerId, // The unique ID of the deployed trigger + name: triggerName, // The name of the deployed trigger + owner_id: userId, // The unique ID in Pipedream of your user +} = deployedTrigger; + +// Parse and return the data you need ``` + + +```bash +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: development" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "external_user_id": "abc-123", + "id": "gitlab-new-issue", + "prop_name": "projectId", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_kVh9AoD" + } + }, + "webhook_url": "https://events.example.com/gitlab-new-issue" + }' +# Parse and return the data you need +``` + + If the source deployment succeeds, the response will contain the information regarding the state of the source, including all the component's props metadata, @@ -622,11 +806,9 @@ this: } ``` -In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete -the source in the future: +In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete, +retrieve, or update the source in the future. -```text -DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9 -``` +Refer to the [full Connect API reference](/connect/api#components) for questions and additional examples. diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 85a430b83d50c..7eb3daed2a689 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2454,8 +2454,7 @@ importers: specifier: ^0.1.6 version: 0.1.6 - components/current_rms: - specifiers: {} + components/current_rms: {} components/customer_fields: dependencies: @@ -7284,8 +7283,7 @@ importers: components/odoo: {} - components/office_365_management: - specifiers: {} + components/office_365_management: {} components/offlight: dependencies: @@ -12645,8 +12643,7 @@ importers: specifier: ^1.0.5 version: 1.0.5 - components/zoho_tables: - specifiers: {} + components/zoho_tables: {} components/zoho_workdrive: dependencies: @@ -32274,6 +32271,8 @@ snapshots: '@putout/operator-filesystem': 5.0.0(putout@36.13.1(eslint@8.57.1)(typescript@5.6.3)) '@putout/operator-json': 2.2.0 putout: 36.13.1(eslint@8.57.1)(typescript@5.6.3) + transitivePeerDependencies: + - supports-color '@putout/operator-regexp@1.0.0(putout@36.13.1(eslint@8.57.1)(typescript@5.6.3))': dependencies: