# Building your connector from an API definition

> 1. If you select **Start from an API definition**, you must provide the API definition:
   * From a local file – Upload a Postman or Swagger collection.
   * From a URL – Enter a file URL, such as `https://petstore.swagger.io/v2/swagger.json`.

## Create a new connector

1. If you select **Start from an API definition**, you must provide the API definition:
   * From a local file – Upload a Postman or Swagger collection.
   * From a URL – Enter a file URL, such as `https://petstore.swagger.io/v2/swagger.json`.

     ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-48887-3f5f76aa.webp)
2. Select **Continue**.

## Configure your connector

1. In the **Confirm import** window, you can:
   * Change the **Provider name**, **Application name**, and **Connector name**.
   * Modify the resources you want to use in your custom connector. All available resources are automatically enabled; disable
     the ones you wish to exclude.
     + Use the **Search** bar to look for a specific resource.
   * Select **Create**.

     ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-432931-480627b5.webp)
2. The **Settings** window is now displayed.
3. In the **Info** tab you can configure the following fields:
   * **Name** - This is reflected in your connector key.
   * **API type** – This field is disabled by default, as only REST is currently supported.
   * **Categories** - You can select from the available categories, such as Artificial intelligence or Marketing, or create your on.
   * **Description** – Enter a description for your connector.
   * **Icon** – Select **Browse** to upload an image from your computer. All image types are supported, but we recommend using a square SVG.
4. **Catalog preview** displays how your custom connector will appear in the Integration Service connector catalog.
5. Select **Save**.

   ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-432942-308d6ec0.webp)

### Configure the Base API

In the **Base API** tab, you configure the base URL for the application API and the pagination:

* **Base URL** – Automatically filled with the value declared at connector creation.
* **Pagination type** – Options available in the drop-down are: Page start with 1, Page starts with 0, Offset, Custom, None. If the vendor documentation
  doesn’t provide any details on pagination, keep the default value. For details, refer to the [Pagination](https://docs.uipath.com/integration-service/automation-cloud/latest/user-guide/from-an-api-definition#pagination) section.
* **Pagination max** – Default value is `100`. If the vendor documentation doesn’t provide any details on pagination, keep the default value.
* **Content-Type header** – This field is disabled by default. Only `application/json` is currently supported.
* **Accept header** – This field is disabled by default. Only `application/json` is currently supported.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-390260-f2fe8f0d.webp)

### Pagination

Pagination allows vendor applications to return portions of a response incrementally rather than all at once, thereby optimizing
response time.

Pagination can be implemented in various ways. UiPath connectors use a standardized pagination
configuration, ensuring all connectors operate the same way.

You can configure pagination settings at connector level in **Settings \> Base API**, by defining the **Pagination type** and **Pagination max** fields. For List-based activities, you can further configure pagination at resource level.

#### Pagination types

The **Pagination type** field offers multiple options, to align with various provider specifications:

* Page starts with 1
* Pages starts with 0
* Offset
* Cursor
* None

The custom connector’s activities will function in your Studio environment regardless of the selected **Pagination type**. However, to ensure you receive full responses, it's important you specify and configure the correct pagination type.

#### Page starts with 1 and Page starts with 0

Page-based pagination types rely on query parameters passed to the provider to indicate what page of the results should be
returned and the number of results per page.

For example, GitHub uses page-based pagination, as explained in [Using pagination in the REST API](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api?apiVersion=2022-11-28). They have included the next page URL in the response header for easier implementation, but the underlying mechanism is based
on the **Page** and **per\\_page** query parameters.

In Connector Builder, you can select one of the following options:

* **Page starts with 1** refers to pagination where the first page of results has an index of one (for example, page=1),
* **Page starts with 0** refers to pagination where the first page of results is at the index of zero (for example, page=0).

#### Resource configuration

By default, page-based pagination assigns **Page** and **pageSize** as the paging parameters. You can override these to provider specifications as follows:

1. Select your resource.
2. Select the **Pagination** tab.
3. Enable pagination and update the parameter names to match the provider's parameters.

#### Cursor pagination

Cursor-based pagination relies on a page token returned from the provider rather than a page or offset number that can be
passed into subsequent calls to return the next page of results.

When you make a request in Connector Builder for a connector that uses cursor-based pagination, the results returned are not
automatically paginated. Therefore, not all results are returned without manually including the next cursor in a subsequent
call.

Similar to other pagination types, cursor-based pagination usually includes a value for specifying the number of results per
page.

#### Resource configuration

Cursor-based pagination provides default names for the cursor and page size (**nextPage** and **pageSize**) which you can override to match provider specifications.

#### Identifying the page token path

The next page cursor is often nested in the API response fields. Therefore, it is important to specify the location of the
cursor in the response schema so that Integration Service can extract the page token value and use it in a subsequent response.

You can specify the location in the response field as follows:

1. Identify where in the response it is located (body or header).
2. Identify the field path with periods separating each level.

If the cursor is nested in a URL, you can use a question mark symbol (`?`) to represent the query parameter to pull.

#### Example

The Meta Graph API offers a good example of using cursor-based pagination in Connector Builder. The [Meta pagination documentation](https://developers.facebook.com/docs/graph-api/results/) specifies where in each request you find the next page token and includes a direct reference to the token or the full URL.
We can use these examples to build out resource pagination for the Meta Graph API.

1. On the selected resource, update the **nextPage** token name and **pageSize** name to match the provider API. According to the Meta Graph API documentation, the **nextPage** token name is **after** and **pageSize** is **limit**.
2. Next, identify where the **nextPage** token is available on each request. The documentation provides us with this JSON that maps the locations:

   ```
   {
     "data": [
        ... Endpoint data is here
     ],
     "paging": {
       "cursors": {
         "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
         "before": "NDMyNzQyODI3OTQw"
       },
       "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw",
       "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
     }
   }
   ```

This is part of the response body, so you can configure the **nextPage** token **in** two ways:

1. Direct map to the page token (preferred): `body.paging.cursors.after`.
2. Use the next URL: `body.paging.next?after`.

Both of these paths provide the connector with the correct location for retrieving the value of the `nextPage` token.

#### Offset pagination

Offset pagination uses record numbers to allow pagination through all response objects. The **Offset** parameter specifies the number of items to skip before starting to return results.

Offset pagination often uses the following two parameters (the exact names may vary)

* **Offset** - indicates the record to start returning results on.
* **Limit** - indicates the number of results per page.

#### Resource configuration

By default, page-based pagination assigns **Page** and **pageSize** as the paging parameters. You can override these to provider specifications as follows:

1. Select your resource.
2. Select the **Pagination** tab.
3. Enable pagination and update the parameter names to match the provider's parameters.

#### Pagination type None

If the provider API does not use pagination, set **Pagination type** to **None**.

#### Resource configuration

If you set Pagination type to **None**, the **Pagination** tab is removed from the **List** activity resources.

#### Pagination max

The **Pagination max** field refers to the maximum number of results the provider can return.

Integration Service has an upper threshold of 2,000 results. To improve efficiency, we recommend using a lower number.

### Set the authentication method

In the **Authentication** tab, you configure the authentication type for your connector. Refer to[Authentication types](https://docs.uipath.com/integration-service/automation-cloud/latest/user-guide/authentication-configuration#authentication-types) for more information on the supported options.

### Test your connection

Once you have completed the authentication configuration, select **Add connection** from the drop-down menu:

If your connection is successful, the status is updated to **Connected**.

### Resources

Connector Builder generates the list of resources based on the provided API definition. The left-side menu displays the list
of available resources, organized in groups.

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-48639-c2685445.webp)

1. Select the More options ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-367213-45418e9f.svg) button menu to further configure each method. You can:
   * **Add method** – Opens the **Create new resource** window.
   * **Allow method deletion** – Activates a **Delete** icon for each resource in the group.
   * **Edit path** – Edit the resource’s path. For example: `[BASE URL]/pet = https://petstore.swagger.io/v2/pet`
   * **Delete** – Deletes a resource group. A message warns you that the operation cannot be undone.
   * **Duplicate** – Opens the **Duplicate resource** window, where you can edit the path, choose a display name and select methods.

     ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-49019-2701c6a4.webp)
2. You can also **Create new resource group** in two ways:
   * **Blank**: Configure the following fields:
     + **Path** - `[Base URL]/[path]`
     + **Display name**
     + **Select methods**: Get, Get By Id, Post, Put, Patch, Delete

       ![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-390244-21e70b2f.webp)
   * From **cURL**: enter a cURL command.

#### Configure your resources

When you select a resource, the following window is displayed:

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-390248-75151684.webp)

Depending on the resource method you select, the following configuration tabs are available: **Parameters**, **Response**/**Request Fields**, **Pagination**, **Search**.

#### Parameters

For example, all four tabs are available for GET methods. For POST methods, only the Parameters, Request Fields, and Response
Fields tabs are displayed.

In **Parameters**, you can view the list available parameters for the selected resource, add new parameters, or import parameters from an existing
resource.

The parameters listed in this table are the ones you will use in Studio when building automations using your custom connector.

The **Pet** object corresponds to the Pet resource group, and the available fields are the ones set for the GETBYID resource:

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-390252-e902393e.webp)

#### Response and Request fields

:::note
Nested array objects are not currently supported.
:::
The **Response** and **Request** fields for each resource are automatically generated upon sending a request.

In each respective tab, you can edit or delete any field. If you select the **Edit** icon, the following configuration window is displayed:

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-48799-122eb529.webp)

In the **Response**/**Request** fields tab, the following options are also available:

* **Overwrite on send request** checkbox - If selected, when you execute a **Send request**, the fields list is regenerated. **Do not** select this option if you added new fields to your resource.
* **Additional options** button:

  | Option | What it does |
  | --- | --- |
  | **Update response root key** | Define the response key when dealing with nested arrays in the response. |
  | **Delete all fields for method** | Deletes all fields for the selected method. |
  | **Generate from payload** | Use a sample payload from the service documentation or an API call to generate the resource fields. |
* **Add row** button - Adds new fields to the resource.

Select the **Visible columns** icon to add or delete columns in the fields table.

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-48859-b9e105c1.webp)

Each color under the **Methods** column corresponds to a certain method: Get, Get by ID, Post, Put, Patch, Delete.

![docs image](https://dev-assets.cms.uipath.com/assets/images/integration-service/integration-service-docs-image-390256-8dca06f8.webp)

#### Pagination

Enable **Pagination** for a resource if you expect a list response. If you enable pagination, you also need to define the **Response root key** in the configuration tab, for nested lists.

#### Search

Activate the **Enable Search** checkbox to allow search setup for a resource.

After you configure everything you need, you can continue with .