API Access

A web API endpoint for executing DSL queries is available. The Python script below illustrates how to make a DSL query using the web API.

Note

The Dimensions Analytics API is limited to 30 requests per IP address per minute.

Python Example

import requests

#   The credentials to be used
login = {
    'username': 'your username',
    'password': 'your password'
}

#   Send credentials to login url to retrieve token. Raise
#   an error, if the return code indicates a problem.
#   Please use the URL of the system you'd like to access the API
#   in the example below.
resp = requests.post('https://<your-url.dimensions.ai>/api/auth.json', json=login)
resp.raise_for_status()

#   Create http header using the generated token.
headers = {
    'Authorization': "JWT " + resp.json()['token']
}

#   Execute DSL query.
resp = requests.post(
    'https://<your-url.dimensions.ai>/api/dsl.json',
    data='search publications return publications'.encode(),
    headers=headers)

#   Display raw result
print(resp.json())

Note

Please note escaping rules in Python. For example, when writing a query with escaped quotes, such as:

search publications for "\"phrase 1\" AND \"phrase 2\""

in Python, it is necessary to escape the backslashes as well, so it would look like:

resp = requests.post(
    'https://<your-url.dimensions.ai>/api/dsl.json',
    data='search publications for "\\"phrase 1\\" AND \\"phrase 2\\""',
    headers=headers)

Similar escaping rules might apply to other programming languages than Python as well.

CURL + JQ Example

This example shows a minimal way to query the API. This should be easily transferable to any other programming language or environment.

export DSL_TOKEN=$(curl https://<your-url.dimensions.ai>/api/auth.json -d '{"username": "your username", "password": "your password"}' -s|jq -r .token)

curl https://<your-url.dimensions.ai>/api/dsl.json -H "Authorization: JWT $DSL_TOKEN" -d 'search publications return publications' -s|jq

Note

Note that jq tool is used to extract a “token” value from the JSON response in the first request. In the second request, jq is used only to pretty print the result so it’s use is optional.

PowerShell Example

This is an equivalent example of the above CURL + JQ Example, but usable in the PowerShell enivornment.

$DSL_TOKEN = (Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/auth.json -Method Post -Body (@{'username' = 'your username'; 'password' = 'your password'} | ConvertTo-JSON)).token

Invoke-RestMethod -Uri https://<your-url.dimensions.ai>/api/dsl.json -Method Post -H @{Authorization = "JWT $DSL_TOKEN"} -Body 'search publications return publications'

Postman Example

This examples shows how to set up Postman to query the Dimensions API. This can be achieved in two simple steps.

1. Obtaining a JWT token

Make a POST request to https://app.dimensions.ai/api/auth.json with body { "username": "<your-username>", "password": "<your-password>"}

This will return a JWT token, which should be noted as it will be used in the next step.

postman example - part 1

2. Using the token to query the API

Make a new POST request by adding the token to the Headers panel in this format: Authorization : JWT {theToken}.

postman example - part 2

Finally, Compose your query in the request body section:

postman example - part 3

Note

Another approach to get started with Postman is by using the cURL importer.