Using the API


DATPROF Runtime contains the powerfull 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(1).

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 this 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 parameter 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 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 }'

(info) 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 }"


{
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 al 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

(1) For information about Redoc check https://rebilly.github.io/ReDoc/

(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/