Creating and deleting destinations in Management API

This article explains how to create and delete destinations, called Target types, with the Management API.

Prerequisites

Before you complete the procedure in this guide, perform all of the following actions:

Create an authorization and determine its CONNECTION_ID. For more information, see Creating and configuring authorizations in Management API.
Create a workspace and determine its WORKSPACE_ID. For more information, see Configuring workspaces in Management API.

Listing available destination types

To list available destination types, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/target-types/
```
In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/target-types/' \
--header 'Authorization: Token {{KEY}}'

Creating a new destination

Listing available options for destination type

Use the API call described below to obtain information about required and optional configuration options for a particular destination. To receive available options for a destination type, follow these steps:

Create an OPTIONS request to the following endpoint:
```
https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/
```
In the response of the call made in the previous section, Listing available destination types, find the TARGET_TYPE_ID of your selected destination. The ID can be 11, for example.
In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.
In the response, all fields with the "required": true parameter and value are options required for the API call described in the section below to create a new destination.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/' \
--header 'Authorization: Token {{KEY}}'

Creating a destination

To create a new destination, follow these steps:

Create a POST request to the following endpoint:

https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/

In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the parameters and values required for the specific destination. These parameters may include the following:

name

Use the new name of your destination.

stack

Use the WORKSPACE_ID of the workspace in which your new destination is to be situated. For more information, see Configuring workspaces in Management API.

auth

Use the CONNECTION_ID of the destination. For more information, see Creating and configuring authorizations in Management API.

Example of the request body:
```
{
    "name": "NEW_DESTINATION_NAME",
    "stack": {{STACK_ID}},
    "auth": {{CONNECTION_ID}}
}
```
Send the request.

When you send the request and miss some of the required parameters, you are reminded which parameters are required for a particular destination in the response of the call.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "NEW_DESTINATION_NAME",
    "stack": {{STACK_ID}},
    "auth": {{CONNECTION_ID}}
}'

There are various optional parameters depending on the specific destination. The list below does not include a vast majority of these parameters. You can search in the response of an API call described in section Listing available options for destination type and use names of destination configuration options from the UI to search for other parameters. For example, in the response, search for option Force string type (UI name). This parameter is named force_string in the API and Force string type is a label of this parameter.

The following list consists of some of these optional parameters:

output_format

For file destinations. This parameter enables you to choose between various output formats that may include: CSV (you can choose from CSV with comma, semicolon, pipes, or tabs), TSV, JSON, NDJSON, AVRO, PARQUET, XLSX.

mode

For database destinations, the values of mode parameter can be 1 (Truncate) or 2 (Append).

schema_mapping

You can enable or disable Data Mapping for all file based destinations. This parameter can take the following values depending on the specific destination:

Boolean true or false for Google Sheets and Google BigQuery destinations.
For File and Azure Blob destinations.
- 0 - Disabled
- 1 - Enabled with metadata
- 2 - Enabled without metadata

Practical example of destination creation

This section documents how to create a new destination demonstrated on an example of Google Sheets.

Listing available options for Google Sheets destination type

Use the API call described below to obtain information about required and optional configuration options for Google Sheets destination. To receive available options for this destination type, follow these steps:

In the response of the call made in the section Listing available destination types, find the Google Sheets destination ID. The ID can be 11, for example.

Create an OPTIONS request to the following endpoint:

https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/

In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.
In the response, all fields with the "required": true parameter and value are options required for the API call described in the section below to create a new destination.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/' \
--header 'Authorization: Token {{KEY}}'

Creating a Google Sheets destination

To create a new destination, using Google Sheets example, follow these steps:

Create a POST request to the following endpoint:

https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/

In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the parameters and values required for the specific destination. For example, Google Sheets destination requires the following fields:

name

Use the new name of your destination.

stack

Use the WORKSPACE_ID of the workspace in which your new destination is to be situated. For more information, see Configuring workspaces in Management API.

auth

Use the CONNECTION_ID of the destination. For more information, see Creating and configuring authorizations in Management API.

Example of the request body:
```
{
    "name": "NEW_DESTINATION_NAME",
    "stack": {{STACK_ID}},
    "auth": {{CONNECTION_ID}}
}
```
Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "NEW_DESTINATION_NAME",
    "stack": {{STACK_ID}},
    "auth": {{CONNECTION_ID}}
}'

Deleting a destination

Retrieving ID of the destination to be deleted

Before deleting a destination, find its ID. To retrieve the ID of the destination, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/

In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.
Search for the relevant ID of the destination to be deleted.
(Optional) Include ?page=2 at the end of the request URL and send the request again. You may find more results as Management API uses pagination. Other pages may contain the relevant result. For example, ?page=3 or ?page=4. The resulting request URL may be similar to the following:

https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/?page=2

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/' \
--header 'Authorization: Token {{KEY}}'

Issuing a delete request

To delete a destination, follow these steps:

Create a DELETE request to the following endpoint:

https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/

In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request DELETE 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/' \
--header 'Authorization: Token {{KEY}}'