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
Script	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
Columns	api/columns/	GET, PATCH
Connection types	api/connection-types/	GET, HEAD, OPTIONS
datastream types	api/datastream-types/	GET, HEAD, OPTIONS
datastreams	api/datastreams/	GET, HEAD, OPTIONS
Errors	api/errors/	GET, HEAD, OPTIONS
Extracts	api/extracts/	GET, HEAD, OPTIONS
Jobs	api/jobs/	GET, HEAD, OPTIONS
Mapping tables	api/mapping-tables/	GET, POST, HEAD, OPTIONS
SQL targets	api/targets/	GET, POST, HEAD, OPTIONS
Stacks (workspaces)	api/stacks/	GET, POST, HEAD, OPTIONS
storage	api/storage/	GET, POST, HEAD, OPTIONS
Target columns	api/target-columns	GET, POST, HEAD, OPTIONS
Target types	api/target-types/	GET, HEAD, OPTIONS
Tasks	api/tasks/	GET, HEAD, OPTIONS
Token info	api/token/info	GET
Transformer	api/transformer/	GET, POST, DELETE, PATCH HEAD, OPTIONS
value tables	api/value-tables/	GET, POST, HEAD, OPTIONS

General workflow note

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

Request initial IDs or basic information with a GET request.
Request available configuration options with an OPTIONS request.
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