Creating and configuring Management API
s inThis guide explains how to search for available Management API, as well as how to list and configure Billing Objects.
types and s, how to create, set up and configure s with theRetrieving subscribed types
To retrieve all subscribed
types, follow these steps:-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/connection-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/connection-types/' \
--header 'Authorization: Token {{KEY}}'
The available instance.
types listed in the response may differ for eachSearching for an
type by nameOptionally, to search for an
types by their name, follow these steps:-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/?search=CONNECTION_TYPE_NAME
Note: Search is included as a URL parameter.
-
Replace the
CONNECTION_TYPE_NAME
with the name retrieved in the response of the API call described in Retrieving subscribed authorization 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/connection-types/?search=CONNECTION_TYPE_NAME' \
--header 'Authorization: Token {{KEY}}'
Listing all s of an type
To list all
s of a specific type, follow these steps:-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/
-
Find the value of parameter
id
and use it in{{CONNECTION_TYPE}}
placeholder. Find the IDs and their values in response to the API call described in Retrieving subscribed authorization 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/connection-types/{{CONNECTION_TYPE}}/connections/' \
--header 'Authorization: Token {{KEY}}' \
Retrieving required options for an type
To retrieve options required to create an
of a certain type, follow these steps:-
Create an OPTIONS request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections
-
Find the value of parameter
id
and use it in the{{CONNECTION_TYPE}}
placeholder. Find the IDs and their values in the response to the API call described in Retrieving subscribed authorization 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.
-
In the response, search for the JSON objects marked as
"required": true
. Use these required objects in the next section, Creating an 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 OPTIONS 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections' \
--header 'Authorization: Token {{KEY}}
'
Creating an
To create an
, follow these steps:-
Create a POST request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/
-
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 valueapplication/json
. -
In the HTTP request body, include the objects marked as
"required": true
in the response of the API call described in Retrieving required options for an authorization type. See the example of the request body below for more information:{ "name": "NEW_CONNECTION", "stack": {{STACK_ID}}, "username": "USERNAME", "password":"PASSWORD" }
For some
types, other options may be required. In the following example of the request body, theapp
option is included.{ "name": "NEW_CONNECTION", "stack": {{STACK_ID}}, "app": "{{APP_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/connection-types/{{CONNECTION_TYPE}}/connections/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "NEW_CONNECTION",
"stack": {{STACK_ID}},
"username": "USERNAME",
"password":"PASSWORD",
"app": {{APP_ID}}
}'
Authorizing an OAuth 2.0
To authorize an
that uses OAuth 2.0 protocol, follow these steps:-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/authorize/
-
For the parameter
CONNECTION_TYPE
, use the value of the parameterid
in the response of the API call described in Retrieving subscribed authorization 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.
-
From the API response, use the URL (the parameter is marked as
url
) to redirect you to the login page of the data provider for your . See the response example below:{ "status": "ok", "is_authorized": false, "is_oauth": true, "url": "https://INSTANCE/oauth2/token/TOKEN_VALUE" }
-
At the data provider website, use your credentials to authorize your
.
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/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/authorize/' \
--header 'Authorization: Token {{KEY}}
'
Creating an authorization and authorizing it
Use this request to create an Adverity.
and generate a link to authorize it inIf you do not have the required credentials for the data source or destination you want to authorize Adverity to access, you can send an email asking someone else to authorize the connection for you.
To create an Adverity, follow these steps:
and generate a link to authorize it in-
Create a POST request to the following endpoint:
https://{{INSTANCE}}/api/connection-invite/
-
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 valueapplication/json
. -
In the HTTP request body, include the following parameters:
Parameter name |
Description |
---|---|
content_types |
Enter a list of dictionaries containing |
.../content_type |
Enter the ID of the type for the new . |
.../name |
Enter a descriptive name for the . |
|
Enter the email of the person who needs to authorize the access. |
notification_emails |
Enter the emails that will be notified once the access is granted or in case of any future issues with the . |
stack |
Enter the stack (workspace) ID. |
email_body |
(Optional) Enter the email body if you want to customize it. The email body must contain {{ user}} and {{ link }} placeholders. If this parameter is not used, the following body will be used:
|
send_invite_email |
(Optional) Set this parameter to |
-
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/connection-invite/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"content_types": [
{
"content_type": "{{CONNECTION_TYPE_ID}}",
"name": "{{CONNECTION_NAME}}"
}
],
"email": "recipient_email@organization.com",
"notification_emails": ["email1@organization.com", "email2@organization.com"],
"stack": {{STACK_ID}}
}'
Response
The response contains the following parameters for each created
:
Response parameter |
Description |
---|---|
link |
Authentication link for the . Open this link to authorize the created .The same link is included in the email body sent to the email address provided in the request body. |
name |
Name of the provided in the request body. |
content_type_id |
type ID provided in the request body. |
The person from whom you are requesting access will receive an email and can authorize the connection using Adverity user interface. For more information, see Responding to an authorization request.
Editing an
The example in this section documents how to change the
name. To edit an existing configuration, follow these steps:-
Create a PATCH request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_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 valueapplication/json
. -
In the HTTP request body, include the parameter and the new value you want to assign to it. For example,
{"name": "NEW_NAME"}
-
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 PATCH 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/' \
--header 'Authorization: Token {{KEY}}
' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "NEW_NAME"}'
Listing and editing Billing Objects
This section of the guide outlines how to perform the following actions:
Billing Objects are entities belonging to an . You can choose which Billing Objects Adverity can access and collect data from. For more information, see the glossary entry for Billing Objects
Starting a metadata update
To start a metadata update and ensure that the list of Billing Objects is up to date, follow these steps:
-
Create a POST request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/update/
-
Replace the
CONNECTION_TYPE_ID
with the type ID retrieved in the response of the API call described in Retrieving subscribed authorization types. -
Replace the
CONNECTION_ID
with the ID retrieved in the response of the API call described in Retrieving required options for an authorization type. In this response, theCONNECTION_ID
is displayed as the value of the parameterid
. -
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 POST 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/update/' \
--header 'Authorization: Token {{KEY}}'
Listing Billing Objects
To see a list of all the Billing Objects for an , follow these steps:
-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}
-
In the HTTP request header, include the parameter
Authorization
with valueToken REMOVED
. -
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 -L -X GET 'https://{{INSTANCE}}.datatap.adverity.com/api/billings/{{CONNECTION_ID}}' \
-H 'Authorization: Token REMOVED'
Enabling access to the selected Billing Objects
Enabling access to the selected Billing Objects disables access to all other Billing Objects by default.
To enable the selected Billing Objects and, as a result, disable access to all other Billing Objects by default, follow these steps:
-
Create a PATCH request to the following endpoint:
https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/
-
In the HTTP request header, include the parameter
Authorization
with valueToken REMOVED
. -
In the HTTP request header, include the parameter
Content-Type
with valueapplication/json
. -
In the HTTP request body, include theIDs of the Billing Objects that you want to enable under the
objects
tag.
To disable all Billing Objects except the selected ones, set theenable_all_billing_objects
parameter to false. -
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 PATCH 'https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/' \
--header 'Authorization: Token REMOVED' \
--header 'Content-Type: application/json' \
--data-raw '{
"objects":[
{
"id": {{ID}},
"is_enabled": true
}
],
"enable_all_billing_objects": false
}'
As a result, the billing object with ID {{ID}}
is enabled and access to all other Billing Objects is disabled by default.
Enabling access to all Billing Objects
To enable access to all and future Billing Objects, follow these steps:
-
Create a PATCH request to the following endpoint:
https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}
-
In the HTTP request header, include the parameter
Authorization
with valueToken REMOVED
. -
In the HTTP request header, include the parameter
Content-Type
with valueapplication/json
. -
In the HTTP request body, include the
enable_all_billing_objects
parameter and set it to true, and include an emptyobjects
list. -
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 PATCH 'https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/' \
--header 'Authorization: Token REMOVED' \
--header 'Content-Type: application/json' \
--data-raw '{
"objects":[
],
"enable_all_billing_objects": true}'
As a result, access is granted to all and future Billing Objects by default.
Exporting a list of available Billing Objects
To export a list of the available Billing Objects for all workspaces to which you have access, follow these steps:
-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/billing-objects/export/
-
In the HTTP request header, include the parameter
Authorization
with valueToken {{KEY}}
and the parameterAccept
with valuetext/csv
. -
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/billing-objects/export/' \
--header 'Authorization: Token {{KEY}}'
--header 'Accept: text/csv'
As a result, you have obtained a list of all available Billing Objects for all workspaces to which you have access.
Deleting an
To delete an
, follow these steps:-
Create a DELETE request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_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.
-
As a result, the
is deleted. In the successful response, you receive an empty JSON body.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/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/' \
--header 'Authorization: Token {{KEY}}'
Updating
tokensTo update an data source APIs that use OAuth 2.0, follow these steps:
token for-
Create a PATCH request to the following endpoint:
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/token/
-
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 valueapplication/json
. -
In the HTTP request body, include the following parameters:
-
access_token
- the access token that you want to update. -
refresh_token
- the refresh token for the . -
expires
- the expiration time for the access token in the DateTime format.
-
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/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/token/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires": "EXPIRATION_DATE"
}'