Getting started with the Management API

Getting started with the Management API#

This article explains some essential information about the Management API.

Management API basics#

The Management API lets you use Adverity through API requests, instead of the Adverity user interface.

Use any HTTP client to interact with the Management API. With Postman, you can use the Adverity Postman collection.

This section of the Adverity documentation contains information about how to make requests to the Management API in order to use the Adverity platform.

Code#

This documentation provides examples of requests you can make to the Management API and responses as code blocks. You can copy them and edit them. For example:

curl --location --request POST 'https://{{INSTANCE}}/api/auth/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username={{USERNAME}}' \
--data-urlencode 'password={{PASSWORD}}'

You can import this code as raw text to Postman or to other HTTP clients.

Placeholders#

In the code block above, you may see the red word {{INSTANCE}} capitalized. This marks the text as a placeholder, where you substitute the text with your own value. Postman allows to change placeholders in double curly brackets as variables in an environment. For more information, see Postman documentation.

Placeholders which are not marked with double curly brackets are still capitalized. For example: Substitute KEY_VALUE with the value of your Adverity API key. Since these placeholders are not marked with double curly brackets, they are not understood as variables by Postman. If required, substitute them manually.

IDs are marked with placeholder value such as 123.

Difference in naming#

Certain elements require additional explanation or carry different names in the UI compared to the API:

UI Name

API Name

Instance

Your Adverity instance. To find your instance, go to the Adverity user interface. Copy the URL that you see in the browser. Remove https:// from the beginning of the URL and the part similar to /workspace-name/ from the end. For example, if the original URL is https://my-organization.datatap.adverity.com/my-workspace/, the result is my-organization.datatap.adverity.com.

Workspace

Stack

Transformation

Transformer

Destination

Target

Target field

Target column

Issues

Errors

Fetch Jobs

Jobs

Endpoints#

To display the API in your browser, in the following link, replace {{INSTANCE}} with your Adverity instance, and then open the link in your browser: https://{{INSTANCE}}/api/

The base URL for all endpoints:

https://{{INSTANCE}}/api/

Example URL for datastreams endpoint:

https://{{INSTANCE}}/api/datastreams/

Example URL for Jobs endpoint:

https://{{INSTANCE}}/api/jobs/

As mentioned above, with Postman, you can use the Adverity Postman collection to see and test available endpoints and requests.

List of endpoints#

The following list provides information about all available endpoints of the Management API.

Endpoint

Endpoint URL

API request types

Auth

api/auth/

POST

Billing Objects

api/billing-objects/

GET

Billings

api/billings/

GET, PATCH

Columns

api/columns/

GET

Connection Invite

api/connection-invite/

POST

Connection Types

api/connection-types/

DELETE, GET, OPTIONS, PATCH, POST

Datastream Types

api/datastream-types/

DELETE, GET, OPTIONS, PATCH, POST

Datastreams

api/datastreams/

GET, OPTIONS, PATCH, POST

Errors

api/errors/

GET

Extracts

api/extracts/

GET

Jobs

api/jobs/

GET, POST

Mapping Tables

api/mapping-tables/

DELETE, GET, PATCH, POST

Notifications

api/notifications/

DELETE, GET, PATCH, POST

Stacks

api/stacks/

GET, PATCH, POST

Storage

api/storage/

GET

Target Columns

api/target-columns/

GET, OPTIONS, POST

Target Types

api/target-types/

DELETE, GET, OPTIONS, POST, PUT

Transformer

api/transformer/

DELETE, GET, PATCH, POST

Value Tables

api/value-tables/

GET

General workflow note#

Often, you can work with the endpoints in the following manner:

  1. Request initial IDs or basic information with a GET request.

  2. Request available configuration options with an OPTIONS request.

  3. Edit the configuration options or create a particular object with a POST or PATCH request.

Additional information#

Rate limits#

Adverity’s Management API has no rate limits. However, each Management API call uses resources, so we recommend that you only perform one Management API task at a time. This avoids overloading your resources and will prevent performance issues. Wait for one Management API call to finish before performing another task.

Timestamps#

Use UTC time zone in all timestamps in the Management API and use the following format:

%Y-%m-%dT%H:%M:%SZ

For example, this translates to the following:

2022-02-01T12:00:22Z

Using filters and ordering data#

All the GET call responses can be filtered by specific parameters. Filter all GET call responses by including the id or date parameters.

To limit the number of results, use the page_size parameter.

https://{{INSTANCE}}/api/jobs/?stack=4&ordering=id&page_size=10
Contents