Skip to content

Adding SDK examples to components API docs #15574

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

Merged
merged 4 commits into from
Feb 12, 2025
Merged

Adding SDK examples to components API docs #15574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7c19ad6
Adding SDK examples to components API docs
dannyroosevelt Feb 12, 2025
0958bd8
Update components.mdx
dannyroosevelt Feb 12, 2025
95f60d2
Update components.mdx
dannyroosevelt Feb 12, 2025
03eddfe
Update components.mdx
dannyroosevelt Feb 12, 2025
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
1 change: 0 additions & 1 deletion docs-v2/pages/connect/api-proxy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import { Tabs } from 'nextra/components'
import Callout from '@/components/Callout'

# Connect API Proxy
Expand Down
284 changes: 233 additions & 51 deletions docs-v2/pages/connect/components.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,68 @@ You can skip steps 1 and 2 if you already know the component you want to use or

<Steps>

### Authenticate to the Pipedream API

Before sending requests to the API, make sure to [authenticate using a Pipedream OAuth client](/rest-api/auth#oauth):

<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```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}"
});
```
</Tabs.Tab>
<Tabs.Tab>
```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}"
}'
```
</Tabs.Tab>
</Tabs>

<Callout type="info">
All subsequent examples assume that you've either initialized the SDK client or have a valid access token.
</Callout>

### 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
<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```javascript
const apps = await pd.getApps({ q: "gitlab" });

// Parse and return the data you need
```
</Tabs.Tab>
<Tabs.Tab>
```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
```
</Tabs.Tab>
</Tabs>

Here's the response:

Expand Down Expand Up @@ -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
<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```javascript
const components = await pd.getComponents({ q: "gitlab" });

// Parse and return the data you need
```
</Tabs.Tab>
<Tabs.Tab>
```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
```
</Tabs.Tab>
</Tabs>

Here's the response:

Expand Down Expand Up @@ -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
<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```javascript
const component = await pd.getComponent({ key: "gitlab-list-commits" });

// Parse and return the data you need
```
</Tabs.Tab>
<Tabs.Tab>
```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
```
</Tabs.Tab>
</Tabs>

The response will contain the component's structure, including its user-friendly name,
version, and most importantly, the configuration options the component accepts
Expand Down Expand Up @@ -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
Expand All @@ -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:

<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```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
```
</Tabs.Tab>
<Tabs.Tab>
```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
```
</Tabs.Tab>
</Tabs>


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:

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand All @@ -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"
Expand All @@ -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
<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```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
```
</Tabs.Tab>
<Tabs.Tab>
```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
```
</Tabs.Tab>
</Tabs>

The output of executing the action will be a JSON object containing the
following fields:
Expand Down Expand Up @@ -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": {
Expand All @@ -559,11 +701,53 @@ look something like this:
}
```

The endpoint to deploy a source is:
Deploy a source for your users:

<Tabs items={['Node.js', 'HTTP (cURL)']}>
<Tabs.Tab>
```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
```
</Tabs.Tab>
<Tabs.Tab>
```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
```
</Tabs.Tab>
</Tabs>

If the source deployment succeeds, the response will contain the information
regarding the state of the source, including all the component's props metadata,
Expand Down Expand Up @@ -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.

</Steps>
Loading
Loading