Using the API

The DATPROF Runtime REST API offers powerful capabilities to integrate Runtime with scripts or external tools for managing projects, environments, and applications.

Key Features:

Automate and streamline Runtime management tasks.
Access detailed API documentation generated using Redoc.
- Includes syntax, response examples, and parameter requirements for all endpoints.

How to Access API Documentation:

Open the Runtime UI.
Locate the "API Docs" option in the bottom-left corner of the screen.
Click to view comprehensive API reference details.

If using the default settings, it’s also possible to navigate to http://localhost:7070/api.html manually. This will also open the API documentation.

The documentation is conveniently available through the left-hand side of the bottom status bar, ensuring quick and easy access for developers and administrators.

Request

The DATPROF Runtime API syntax is always case sensitive!

As of version 3.12.0 all dashes are removed from the API URL, the parameters and the Request Body. (i.e.: project-id has become projectId}

In addition to the syntax description in the generated documentation the following applies:

ALL API calls require an API Token: in curl and Wget syntax this is placed in the Header section:

^{-- header "X-auth-token:<TOKEN>" or -H "X-auth-token:<TOKEN>"}

To test your API calls you may use a graphical tool like Postman.

API calls without parameters

Some API Calls do not require any parameters and can be used as is:

To obtain a list of projects using curl:

^{$ curl -X GET -s -H "X-auth-token:<TOKEN>"}^{http://localhost:7070/api/2/projects}

Result:

^[
^{
^{"id": 1,}
^{"name": "Project1"}
^}

^{

^{"id": 2,}

^{"name": "Project2"}

^{} ]}

API calls using Path parameters

Some API calls require PATH Parameters. Path parameters are part of the URL.

To obtain the run.log of the run with run id 100 using curl:

$ curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/runs/100/log

Result:

^{Project: Project1}
^{Environment: Env1}
^{Application: Privacy1 (1.0.1)}
^{Scenario: anonymize}
^{Start date: 2018-06-12 08:54:31.95}
^{End date: 2018-06-12 11:10:13.70}
^{Duration: 02:15:41.753}
^{Connection: jdbc:oracle:thin:TEST1/*****@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)}

^{(HOST=dpf-test-1)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SID=orcltst1.testdomain)))}
^{Status: DONE}

^{2018-06-12 08:54:32.63 start Process Project141 (try: 0, cycle: 0)}
^{2018-06-12 08:54:32.79 start Process Privacy prepare process (try: 0, cycle: 0)}
^{2018-06-12 08:54:32.89 start Process Drop and create control tables. (try: 0, cycle: 0)}
^{2018-06-12 08:54:33.14 start sqlplus Drop Table DPF_TABLES (try: 0, cycle: 0)}
^{2018-06-12 08:54:33.14 start sqlplus Drop Table DPF_COLUMNS (try: 0, cycle: 0)}
^{2018-06-12 08:54:33.14 start sqlplus Drop Table DPF_FUNCTIONS (try: 0, cycle: 0)}

^<snip>

API calls using Query parameters

Some API calls require QUERY Parameters. Query parameters are appended to the URL using a question mark "?" as separator.

To get a list of parameters of the environment with id 1 using curl:

$ curl -X GET -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/parameters?environmentId=1

Result:

[

^{
^{"id": 12,}
^{"name": "DPF_AUTO_RETRY",}
^{"value": "10",}
^{"default-value": "10",}
^{"type": "STRING",}
^{"userDefined": false,}
^{"description": ""}
^},
^{
^{"id": 11,}
^{"name": "DPF_BYPASS_LOGGING",}
^{"value": "true",}
^{"defaultValue": "true",}
^{"type": "BOOLEAN",}
^{"userDefined": false,}
^{"description": ""}
^},

^<snip>

^]

API calls using a Request Body

Some API Calls require a Request Body. A request body is of the type JSON. You should add the content-type in the request. Using curl this implies the additional header: -H "Content-Type:application/json”

To create a parameter SEASON with value SUMMER in environment with id 1 using curl:

Valid Parameter TYPES are "STRING" and "BOOLEAN"

$ curl -X POST -s -H "X-auth-token:<TOKEN>" -H "Content-Type:application/json" http://localhost:7070/api/2/parameters -d '{ "name":"SEASON","value":"SUMMER","defaultValue":"SUMMER", "description":"Current Season","type":"STRING","environmentId":1 }'

{
Result:

^{"id": 25,}
^{"name": "SEASON",}
^{"value": "SUMMER",}
^{"defaultValue": "SUMMER",}
^{"type": "STRING",}
^{"userDefined": true,}
^{"description": "Current Season"}
^}

Mind the additional Header section and the single quotes around the JSON data section.

Curl under windows

Using curl under windows enclose the data in double quotes and to backquote the inner double quotes.

The example shows the Request body parsed as data parameter: -d "{\"something\"}"

C:\apps\runtime> curl -X POST -s -H "X-auth-token:<TOKEN>" -H "Content-Type:application/json" http://localhost:7070/api/2/parameters -d "{ \"name\":\"SEASON\",\"value\":\"SUMMER\",\"defaultValue\":\"SUMMER\", \"description\":\"Current Season\",\"type\":\"STRING\",\"environmentId\":1 }"

Output

The output of an API v2 call is mostly a JSON object which can be parsed with tools like jq.

First get all the environments for project 1 using project id 1 using curl:

$ curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/environments?projectId=1

Result:

^{[ { "id": 1, "name": "Env1" }, { "id": 2, "name": "Env2" }, { "id": 3, "name": "Env3" } ]}

Now the same call with the additional parsing using jq:

$ curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/environments?project-id=1 | jq ".[] .id"

Output:

¹

²

³

Now to get the ID of environment 2

$ curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/environments?project-id=1 | jq ".[] | select (.name==\"Env2\") | .id"

Output:

2

Another example, get the ID of project name Project1:

$ curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/projects | jq ".[] | select (.name==\"Project1\" ) | .id"

Output:

1

A Wget example on Windows

Start scenario refill

wget --header="X-Auth-Token: <TOKEN>" http://localhost:7070/api/2/runs --post-data="{ \"environmentId\":1,\"scenarioName\":\"refill\"}" --header="Content-Type:application/json"

A curl example on Windows with all the steps to start a scenario.

# 1 GET PROJECTS
curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/projects

# Okay, lets say projetcId 1 is the correct one:
# 2 GET ENVIRONMENTS
curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/environments?projectId=1

# Okay, lets says environemnetId 3 is the correct one:
# 3 GET SCENARIOS
curl -X GET -s -H "X-auth-token:<TOKEN>" http://localhost:7070/api/2/scenarios?environmentId=3

# Okay, lets say scenario "anonymize" is the correct one:
# 4 START SCENARIO
curl -X POST -s -H "X-auth-token:<TOKEN>" -H "Content-Type:application/json" http://localhost:7070/api/2/runs -d "{\"environmentId\":\"3\",\"scenarioName\":\"anonymize\"}"

External links

For more information about Redoc check: https://rebilly.github.io/ReDoc/

For more information about curl check: https://curl.haxx.se/

For more information about postman check: https://www.getpostman.com/

For more information about jq check: https://stedolan.github.io/jq/

For more information about wget check: https://www.gnu.org/software/wget/