The basic usage of the Admin Interface REST API is explained here. For a complete list of available API functions, please refer to the Admin Interface itself.

Overview

The Admin Interface API exposes most of the functionality that is available in the Admin Interface GUI using a RESTful API where resources like systemstatus, logs, tasks etc. can be accessed.

In the examples that follow, the URL: localhost:8080/api/ is being used. This URL will differ per installation.

Authentication and Authorization

When using the Admin Interface API it’s important to follow the following flow:

• Login to start a session

• Pass session id to every request

• Logout to stop session

Login

The login endpoint should be used to start a session with the Admin Interface API. Basic Authentication should be used with the username and access key as registered in the admin interface.

In the following example the user aiuser with access key 8bafr_cZWXaRKppOFssJgNmgYCC8kPWFajmBGi6E is used to login using basic authentication.

$ curl -v -u aiuser:8bafr_cZWXaRKppOFssJgNmgYCC8kPWFajmBGi6E 'http://localhost:8080/api/v1/login'

When authentication is successful a session id is generated called JSESSIONID. The session is returned by the login api and is also written as a cookie in the response. The session is invalid if not used for 15 minutes or more.

Session

When calling api endpoints, the session id should be passed as a cookie. In the following example the system status is requested by passing the session id.

$ curl -v --cookie "JSESSIONID=DEAC2C697393C636AEEC22EAEBDCCAB0" 'http://localhost:8080/api/v1/systemstatus'

Note that when used in a typical web application the cookie is automatically passed with each request.

CSRF

Since 2020.02 the security of the Admin Interface API has been strengthened by requiring a CSRF (Cross Site Request Forgery) header or parameter when using API calls that change the state of the database. This means for all POST, DELETE and PATCH api calls, a dedicated request parameter or header is required.

When using the login api, a CSRF header is sent in the response that looks as follows:

X-CSRF-HEADER: X-CSRF-TOKEN
X-CSRF-PARAM: _csrf
X-CSRF-TOKEN: 7f4acee4-9053-4249-b756-ccf5aa1dc5b5

This tells the api clients to pass the CSRF token using the header named: "X-CSRF-TOKEN" or the request parameter named: "_csrf".

Logout

When done using the API it is recommended to logout the session to free all resources. If not explicitly called, the session will invalidate after 15 minutes. In case the API is used periodically, for example to display status information every 5 minutes, it is recommended to reuse the session token. In that case the logout endpoint should not be used.

$ curl -v --cookie "JSESSIONID=DEAC2C697393C636AEEC22EAEBDCCAB0" 'http://localhost:8080/api/v1/logout'

System Status

Get system status

The systemstatus resource can be used to get status about the live system.

Example request

$ curl 'http://localhost:8080/api/v1/systemstatus' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 4593

{"statusDate":1548848408175,"forecastingShellServersStatus":0,"forecastingShellServersStatusDescription":"OK","masterControllers":[{"mcId":"roadmapmc00","status":0,"statusDescription":"OK","mcStatus":40,"mcStatusDescription":"Fully operational.","pendingTasks":0,"runningTasks":0,"activeUsers":0,"lastHeartBeat":1548848399132,"lastHeartBeatTimeFormatted":"30/01/2019 11:39","softwareVersion":"MasterController:stable_2018.02 (80682)","schemaVersion":"db schema version","dbVersion":"PostgreSQL 9.6","remoteMc":false,"mcSynchronization":{"remoteMcId":"roadmapmc00","status":"Disabled","statusCode":-2,"summary":"MCSynch roadmapmc00, last heartbeat=never, last table=null, last synchLevel=-1, last maxAgeMillis=0, last successful synch start time=never, last failed time= never, this month: inserted bytes=0 B, inserted rows=0, inserted failed rows=0, updated bytes=0 B, updated rows=0, updated failed rows=0, duration=0s, down duration=0s, total: inserted bytes=0 B, inserted rows=0, inserted failed rows=0, updated bytes=0 B, updated rows=0, updated failed rows=0, duration=0s, down duration=0s"},"fssGroups":[{"fssGroupId":"linux","fssGroupName":"Linux","description":"Linux group","priority":0,"allowUnMapped":true,"readyCount":1,"maxAwakeCount":1,"statusCode":0,"statusDescription":"OK"}],"alive":true,"statusOk":true,"statusFailed":false,"statusUnknown":false,"statusFailedOver":false},{"mcId":"roadmapmc02","status":0,"statusDescription":"OK","mcStatus":40,"mcStatusDescription":"Fully operational.","pendingTasks":0,"runningTasks":0,"activeUsers":0,"lastHeartBeat":1548848399132,"lastHeartBeatTimeFormatted":"30/01/2019 11:39","softwareVersion":"MasterController:stable_2018.02 (80682)","schemaVersion":"db schema version","dbVersion":"Oracle 12.1","remoteMc":true,"mcSynchronization":{"remoteMcId":"roadmapmc02","status":"Enabled","statusCode":1,"summary":"MCSynch roadmapmc02, last heartbeat=Wed Jan 30 11:39:45 GMT 2019, last table=ConfigRevisionSets, last synchLevel=-1, last successful synch start time=Wed Jan 30 11:39:38 GMT 2019, last failed time= never, this month: inserted bytes=14 MB, inserted rows=22041, inserted failed rows=0, updated bytes=115 MB, updated rows=22041, updated failed rows=0, duration=6h 23m 30s, down duration=3s, total: inserted bytes=16 MB, inserted rows=25927, inserted failed rows=0, updated bytes=115 MB, updated rows=935857, updated failed rows=0, duration=6h 35m 18s, down duration=7s"},"fssGroups":[{"fssGroupId":"windows","fssGroupName":"Windows","description":"Windows group","priority":0,"allowUnMapped":true,"readyCount":1,"maxAwakeCount":1,"statusCode":-1,"statusDescription":"Failed"}],"alive":true,"statusOk":true,"statusFailed":false,"statusUnknown":false,"statusFailedOver":false}],"forecastingShellServers":[{"fssId":"2460","mcId":"roadmapmc00","fssGroupId":"windows","status":105,"statusDescription":"Init Data Store","taskRunStatus":"C","taskRunStatusDescription":"Complete","workflowId":"workFlowId","runningWorkflowId":"runningWorkflowId","taskRunId":"unknown","dispatchTime":1548848407235,"dispatchTimeFormatted":"30/01/2019 11:40","heartbeatTime":1548848407235,"heartbeatTimeFormatted":"30/01/2019 11:40","hostName":"dw-024.xtr.intra","hostSlotCount":3,"memoryMB":4095,"indexAtHost":1,"cpu":2.0,"directory":"/opt/fews/fss/1","remoteMc":false,"statusOk":true,"statusFailed":false,"statusUnknown":false}],"masterControllerComponents":{"mcStatusExpired":false,"taskRunnerStatusCode":0,"rollingBarrelStatusCode":0,"systemAlerterStatusCode":0,"taskRunnerStatusDescription":"OK","rollingBarrelStatusDescription":"OK","rollingBarrelSummary":"last successful rolling barrel start time=Wed Jan 30 11:39:44 GMT 2019, this month: startedCount=4081, failed=0, failed run=0, duration=10m 2s, down duration=0s, expired=0, extended=0, total: started=9365, failed=23, success=9338, duration=13m 26s, down duration=0s, expired=0, extended=0","systemAlerterStatusDescription":"OK"},"synchronizationStatus":[{"remoteMcId":"roadmapmc02","status":"Enabled","statusCode":1,"summary":"MCSynch roadmapmc02, last heartbeat=Wed Jan 30 11:39:45 GMT 2019, last table=ConfigRevisionSets, last synchLevel=-1, last successful synch start time=Wed Jan 30 11:39:38 GMT 2019, last failed time= never, this month: inserted bytes=14 MB, inserted rows=22041, inserted failed rows=0, updated bytes=115 MB, updated rows=22041, updated failed rows=0, duration=6h 23m 30s, down duration=3s, total: inserted bytes=16 MB, inserted rows=25927, inserted failed rows=0, updated bytes=115 MB, updated rows=935857, updated failed rows=0, duration=6h 35m 18s, down duration=7s"}]}

Response structure

Collected System Logs as zip file

The systemstatus/logs/collect resource can be used to collect all log files of the live system.

Example request

$ curl 'http://localhost:8080/api/v1/systemstatus/logs/collect?uuid=myuniqueuuid' -i -X GET

Request parameters

To track the status of the the download, the uuid that has been passed as parameter can be used to call the session/status endpoint:

$ curl 'http://localhost:8080/api/v1/session/status?uuid=myuniqueuuid' -i -X GET

If the download is still in progress, the status will return 'downloading'.

Example response

HTTP/1.1 200 OK
Content-Type: application/zip; charset=utf-8
content-disposition: attachment; filename="CollectedLogFiles-20210325-085841.zip"
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Response structure

The response is a binary zip file of Content-type application/zip

Database Connections

Since 2020.01

The systemstatus/database/connections resource can be used to get information about the used database connections in the live system.

Example request

$ curl 'http://localhost:8080/api/v1/systemstatus/database/connections' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 343

{"databaseConnections":{"numberOfDatabaseConnections":10,"maxNumberOfDatabaseConnections":100},"operatorClientConnections":{"numberOfOperatorClientConnections":5,"maxNumberOfOperatorClientConnections":40},"forecastingShellServerConnections":{"numberOfForecastingShellServerConnections":4},"serviceConnections":{"numberOfServiceConnections":1}}

Response structure

Logs

The logs resource is used to retrieve and search log messages.

List logs

A GET logs request that will list, filter and sort log messages.

Example request

$ curl 'http://localhost:8080/api/v1/logs?draw=1&start=0&length=100&order%5B0%5D%5Bcolumn%5D=1&order%5B0%5D%5Bdir%5D=asc&entryDateFrom=1549834108000&entryDateTo=1550093313000&level=INFO&source=FS%25205%2520ukeafffsmc00%253A000026752%2509&code=TaskRun.Completed&text=Task&build=81204&taskRunIds=roadmapmc00:003803615' -i -X GET

Request parameters

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 249

{"draw":0,"recordsTotal":100,"recordsFiltered":100,"logs":[{"logEntryId":1,"taskRunId":"taskRunId 1","code":"Code 1","entryTime":1616659205050,"level":"INFO","source":"source 1","text":"Text","build":1234,"componentId":"mc1","eventAcknowledged":0}]}

Response structure

Acknowledge logs

A POST logs/acknowledge request that will acknowledge all passed logEntries.

Since 2020.02 the CSRF parameter or header is required

Example request

$ curl 'http://localhost:8080/api/v1/logs/acknowledge?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5&logEntries=1%7CNLRIMC00:006283806&logEntries=2%7CNLRIMC00:006283806' -i -X POST

Request parameters

Tasks

The task resource is used to retrieve and search tasks.

List tasks

A GET task request that will list all tasks. Optional parameters can be used to filter and sort the results.

Example request

$ curl 'http://localhost:8080/api/v1/tasks/scheduled?draw=1&start=0&length=100&order%5B0%5D%5Bcolumn%5D=description&order%5B0%5D%5Bdir%5D=asc&hideOneOffTask=false&hideFinishedTask=false&hideScheduledTask=false&showCurrentForecastDispatchTime=true' -i -X GET

Request parameters

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 686

{"draw":1,"recordsTotal":100,"recordsFiltered":100,"tasks":[{"taskId":"1","description":"Task1","workflowId":"workflow1","whatifId":"whatifid1","whatifName":"whatifname1","tag":"tag1","mcId":"MC01","priority":0,"interval":"week","nextDueTime":0,"endTime":null,"taskStatus":"status","latestTaskRunDispatchTime":0,"latestTaskRunStatus":"status","latestTaskRunTime":null,"latestTaskRunScheduledTime":null,"latestTaskRunCompletionTime":null,"runOnFailover":0,"approve":null,"taskRepeatTime":null,"currentForecastDispatchTime":1583151306,"currentForecastDispatchTimeBackgroundColor":"#ff0000","failoverPolicy":"RUN_DUTY"}],"remoteMcAvailable":true,"whatIfAvailable":true,"tagAvailable":true}

Response structure

List Task Runs

The tasks/{taskid}/taskruns resource is used to get all taskruns for a specified task id.

Example request

$ curl 'http://localhost:8080/api/v1/tasks/ukeafffsmc00:0005697/taskruns' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 736

{"draw":1,"recordsTotal":2,"recordsFiltered":2,"taskRuns":[{"taskRunId":"ukeafffsmc00:000454201","taskId":"ukeafffsmc00:000219891_00000002","description":"Description 1","workflowId":"Calculate_CWI ","scheduledDispatchTime":1570708408,"taskDispatchTime":1570708408,"completionTime":1570713408,"fssId":"1","fssHostName":"myhost","fssDirectory":"/opt/fews/fss/1","status":"Complete","runTime":5000},{"taskRunId":"ukeafffsmc00:000454148","taskId":"ukeafffsmc00:000219891_00000002","description":"Description 1","workflowId":"Calculate_CWI ","scheduledDispatchTime":1570708408,"taskDispatchTime":1570708408,"completionTime":1570714408,"fssId":"2","fssHostName":"myhost","fssDirectory":"/opt/fews/fss/2","status":"Complete","runTime":6000}]}

Response structure

Files

The files/importstatus resource is used to get the status of data feeds.

Import Status

A GET request that will get the import status of all data feeds.

Example request

$ curl 'http://localhost:8080/api/v1/files/importstatus' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 305

{"draw":0,"recordsTotal":1,"recordsFiltered":1,"importStatus":[{"mcId":"MC01","dataFeed":"E2O.Server.Evaporation","directory":"https://wci.earth2observe.eu","lastImportTime":1562532231142,"lastFileImported":"penmanmonteith-agg.nc","filesRead":0,"filesFailed":0,"lastImportTimeBackgroundColor":"#ff0000"}]}

Response structure

Config Management

Since 2020.02

The configmanagement resource can be used to configure the Delft-FEWS live system. It can be used to upload a Config Management patch, a Base Build, a Server Configuration file and a Delft-FEWS configuration.

Upload Configuration Manager patch .jar file

The POST configmanagement/cmpatch resource can be used to upload a Delft-FEWS Configuration Manager patch file. The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf parameter is required.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/cmpatch?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
    <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@patch.jar 'http://localhost:8080/api/v1/configmanagement/cmpatch?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing the file.

HTTP Content-Type:

 Content-Type:
 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary2IBqhL2o3MWn7xgV

HTTP Body:

------WebKitFormBoundary2IBqhL2o3MWn7xgV
Content-Disposition: form-data; name="file"; filename="patch.jar"
Content-Type: application/octet-stream


------WebKitFormBoundary2IBqhL2o3MWn7xgV--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded jar file.

{"errors":[],"fileName":"patch.jar"}

Response structure

Upload Base Build zip file

The POST configmanagement/basebuilds resource can be used to upload a base build zip file. The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf parameter is required.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/basebuilds?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
     <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@basebuild.zip 'http://localhost:8080/api/v1/configmanagement/basebuilds?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing the file.

HTTP Content-Type:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary2ZaiDB3DrK1rO1QA

HTTP Body:

------WebKitFormBoundary2ZaiDB3DrK1rO1QA
Content-Disposition: form-data; name="file"; filename="basebuild.zip"
Content-Type: application/x-zip-compressed


------WebKitFormBoundary2ZaiDB3DrK1rO1QA--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded zip file.

{"errors":[],"fileName":"basebuild.zip"}

Response structure

Upload Master Controller Configuration XML file

The POST configmanagement/mcconfig resource can be used to upload and download the Master Controller Configuration XML file. The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf parameter is required.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/mcconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
     <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@mc-server-config.xml 'http://localhost:8080/api/v1/configmanagement/mcconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing the file.

HTTP Content-Type:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryA9AwoUoMiBpVKdAU

HTTP Body:

------WebKitFormBoundaryA9AwoUoMiBpVKdAU
Content-Disposition: form-data; name="file"; filename="mc-server-config.xml"
Content-Type: text/xml


------WebKitFormBoundaryA9AwoUoMiBpVKdAU--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded xml file.

{"errors":[],"fileName":"mc-server-config.xml"}

Response structure

Download Master Controller Configuration XML file

The GET configmanagement/mcconfig resource can be used to download the current Master Controller Configuration XML file.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/mcconfig' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Disposition: attachment; filename="2021_03_25_08_58_null_mcConfig.xml"
Content-Length: 630
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

<?xml version="1.0" encoding="UTF-8"?> <mc xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/mc.xsd" xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <mcId>MC00</mcId> <logging> <debugEnabled>false</debugEnabled> <rollingTotalSizeMB>5</rollingTotalSizeMB> <queryMinimalExecutionTime unit="hour" multiplier="1"/> <logEntryExpiryTime unit="day" multiplier="5"/> <windowsEventLogEnabled>false</windowsEventLogEnabled> <linuxSyslogFacility>local6</linuxSyslogFacility> </logging> </mc>

Upload Delft-FEWS Configuration zip file

The POST configmanagement/fewsconfig resource can be used to upload a Delft-FEWS configuration zip file. An optional description can be set using the "description" parameter. The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf request parameter is required. When using a description, the description fields should be the first part of the multipart post.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/fewsconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
    <input type="text" name="description"/>
    <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@config.zip 'http://localhost:8080/api/v1/configmanagement/fewsconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing an optional description and the required zip file.

HTTP Content-Type:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundarygXHJQDccIhgKRTLo

HTTP Body:

------WebKitFormBoundarygXHJQDccIhgKRTLo
Content-Disposition: form-data; name="description"

My config changes
------WebKitFormBoundarygXHJQDccIhgKRTLo
Content-Disposition: form-data; name="file"; filename="config.zip"
Content-Type: application/x-zip-compressed


------WebKitFormBoundarygXHJQDccIhgKRTLo--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded zip file.

{"errors":[],"fileName":"config.zip"}

Response structure

System Control

Since 2021.01

The systemcontrol resource can be used to control the Delft-FEWS live system. For example, it can be used to enable or disable the synchronization of a dual MC system.

Enable/Disable MC Synchronization

The POST systemcontrol/mcsynchronization resource can be used to enable or disable the MC synchronization. The _csrf parameter is required.

Example request

$ curl 'http://localhost:8080/api/v1/systemcontrol/mcsynchronization?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5&mcId=mc00&enabled=true' -i -X POST

Request parameters

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 47

{"data":[{"enabled":true,"remoteMcId":"mc01"}]}

Response structure