Using the API
DATPROF Runtime contains the powerful REST API.
This API can be used in your scripts or other tooling to manage Runtime projects, environments and/or applications.
This API system comes along with generated online documentation using Redoc.
To access the documentation, navigate to your Runtime UI and click "API Docs" on the bottom left corner of the screen.
It shows the syntax, respons examples and required parameters.
You can access the documentation at the right corner of the Bottom status bar in the Runtime application.
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 a token: in curl(2) and wget(5) 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(3).
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/projectsResult:
[
{
"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 questionmark "?" 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 }'
(i) 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 }"
{
Result:
"id": 25,
"name": "SEASON",
"value": "SUMMER",
"defaultValue": "SUMMER",
"type": "STRING",
"userDefined": true,
"description": "Current Season"
}
Output
The output of an API v2 call is mostly a Json object which can be parsed whith tools like jq(4).
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:
1
2
3
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
(2) For information about curl check https://curl.haxx.se/
(3) For information about postman check https://www.getpostman.com/
(4) For information about jq check https://stedolan.github.io/jq/
(5)For information about wget check: https://www.gnu.org/software/wget/