Configuring and editing datastreams in Management API

This guide explains how to configure and edit datastreams with the Management API.

Listing datastreams of a specific type

To list datastreams of a specific Datastream Type, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/
```
Replace {{DATASTREAM_TYPE}} with the Datastream Type's ID. For more information on determining a Datastream Type's ID, see Determining a Datastream Type's 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.

As a result, you obtain the list of datastreams of a specific Datastream Type.

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/datastream-types/{{DATASTREAM_TYPE}}/datastreams/' \
--header 'Authorization: Token {{KEY}}'

Example of JSON response:

{
    "count": 15,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": {{DATASTREAM_ID}},
            "cron_type": "day",
            "cron_interval": 1,
            "cron_start_of_day": "00:30:00",
            "cron_interval_start": 1,
            "time_range_preset": 13,
            "delta_type": 2,
            "delta_interval": 1,
            "delta_interval_start": 1,
            "delta_start_of_day": "00:00:00",
            "datatype": "Staging",
            "creator": "jane@doe.com",
            "datastream_type_id": {{DATASTREAM_TYPE}},
            "absolute_url": "https://{{INSTANCE}}/adform/{{DATASTREAM_ID}}/adform-buyer/"
        }
    ]
}

The value in an id parameter of the response is a datastream's ID.

Determining current datastream configuration

To determine a datastream's current configuration, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/
```
Replace {{DATASTREAM_ID}} with the datastream's 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.

As a result, you determined the current datastream configuration.

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/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Determining datastream configuration options

To determine the options you can configure for a datastream, follow these steps:

Create an OPTIONS request to the following endpoint: Replace {{DATASTREAM_ID}} with the datastream's ID.
```
https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_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.

As a result, you obtained the list of options you can configure for the datastream.

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/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/' \
--header 'Authorization: Token {{KEY}}'

In the response, search for specific parameters and objects to edit your datastream configuration. If a specific object includes the parameter read_only with the value true, you cannot edit it. "read_only": false means that you can edit a particular object.

Configuring a datastream

To configure a datastream, follow these steps:

Create a PATCH request to the following endpoint:
```
https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/
```
Replace {{DATASTREAM_ID}} with the datastream's 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.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the names of the datastream configuration options as parameters. Specify a new value for each option.
Send the request.

As a result, you configured the datastream.

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

curl --location --request PATCH 'https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token {{KEY}}' \
--data-raw '{"name": "NEW_VALUE"}'

Listing options for filters

When configuring filters in a datastream, you can only choose from a limited set of options. For example, in the Advertiser filter, you can only choose from a specific list of advertisers. The list is populated by advertisers about which the authorization you use to connect to the data source is authorized to collect data.

To obtain the list of options for a filter, given a Datastream Type and an authorization, follow these steps:

Determine the ID of the authorization you use to connect to the data source.
Determine the Datastream Type's ID.
Determine the Datastream Type options.

In the response, search for the filter you want to configure. For example, the result may contain the following information about the advertisers filter:

"advertisers": {
    "type": "multiple choice",
    "required": false,
    "read_only": false,
    "label": "Advertisers",
    "help_text": "If left blank, data for all advertisers available will be retrieved.",
    "lookup": {
        "url": "/adform/adformdatastream/advertisers/",
        "arguments": [
            "auth"
        ]
    }
},

Note the value of the url parameter in the response.

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/URL_FOUND_IN_RESPONSE_OF_PREVIOUS_STEP/?auth=CONNECTION_ID
```
Replace URL_FOUND_IN_RESPONSE_OF_PREVIOUS_STEP with the value of the url parameter from the previous step, and replace CONNECTION_ID with the ID of the authorization you use to connect to the data source.
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.

As a result, you obtain the list of options for the filters, given this Datastream Type and authorization.

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}}/adform/adformdatastream/advertisers/?auth=123' \
--header 'Authorization: Token {{KEY}}'

Example of JSON response:

{
    "err": "nil",
    "results": [
        {
            "id": 123,
            "text": "Advertiser1"
        }
        {
            "id": 124,
            "text": "Advertiser2"
        }
    ]
}

Deleting a datastream

To delete a datastream, follow these steps:

Create a DELETE request to the following endpoint:
```
https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/
```
- Replace {{DATASTREAM_TYPE}} with the Datastream Type's ID. For more information on finding a Datastream Type's ID, see Determining a Datastream Type's ID.
- Replace {{DATASTREAM_ID}} with the datastream's 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.

As a result, you deleted the datastream.

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

curl --location --request DELETE 'https://{{INSTANCE}}/api/datastream-types/{{DATASTREAM_TYPE}}/datastreams/{{DATASTREAM_ID}}/' \
--header 'Authorization: Token {{KEY}}'