For the list of all supported Decision Insight downloads and releases, see the Downloads page.

Administration and monitoring REST API

Axway Decision Insight (DI) provides a set of REST API that are aimed to automate the administration of the product.

User authenticated API

How to access the API

The API is available through the same HTTP/HTTPS interface as the UI, that is http://localhost:8080/rest. Credentials must be provided through Basic AUTH in order to check if the required operation is permitted.

API URLs and required permissions

The following table lists the available API URLs and the permissions you must have to be able to execute them. For more information about DI permissions, see Managing rights.

URL Required permission Description
/rest/admin/provisioning/application Manage the application Application import/export
/rest/admin/provisioning/application-properties Manage the application Application properties import/export

/rest/admin/provisioning/users

Manage users and roles Users import/export

/rest/admin/licences

Bypass Security Licences management

/rest/admin/properties/overrides

Access administration tools Dynamic properties management
/rest/admin/checkpoints Access administration tools Checkpoint management
/rest/admin/computing/activeRecomputingPeriod Access administration tools Active recomputing period management

/rest/admin/routes

Data collection Data integration routes management

/rest/admin/connectors

System integration Data integration connectors management

/rest/admin/notifications

Notification Notifications management

Security best practices
You must never upload untrusted files to your installation. Make sure to have every file scanned by an anti-malware software before it can be used in the product.

Provisioning

Application import/export - /rest/admin/provisioning/application 

This API enables the import and export of an .APPX file into the node. If an application is already present, only an APPX file that corresponds to the same application can be imported.

Resource Verb Description Parameters

/rest/admin/provisioning/application

GET Export application

format

Format of the exported file. Optional, can be:

  • zip (the default value)
  • tgz : this format can be used only with the rest API. It's not compatible with the UI
PUT Import application format

Format of the file to be imported. Optional, can be:

  • zip (the default value)
  • tgz
importDate

Date of the import (ISO8601 format), optional.

If not specified:

  • In case there is no application, the import date will be today at midnight.
  • In case there is already an application, the latest application version will be overridden by this import.

If specified:

  • in case there is no application, the first application version will be created at this date
  • in case there is already an application, a new application version will be created at this date. The date must be at least 1 minute later than the latest version date.

Examples:

# Application export
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/provisioning/application > export.appx


# Application import
curl -s -S -u <username:password> -H "Content-type: application/octet-stream" -X PUT http://localhost:8080/rest/admin/provisioning/application?importDate=2019-03-01T00:00:00.000 --data-binary @my_application.appx

Application properties import/export - /rest/admin/provisioning/application-properties 

This API enables the import and export of an application properties, for example, data integration properties.

Resource Verb Description Parameters

/rest/admin/provisioning/application-properties

GET Export properties passphrase Mandatory, the passphrase used to encrypt password properties values in the exported file.
PUT Import properties passphrase Mandatory, the passphrase used to decrypt password properties values from the imported file.

Examples:

# Application properties export
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/provisioning/application-properties?passphrase=12345678 > app.properties.xml

# Application properties import
curl -s -S -u <username:password> -H "Content-type: application/octet-stream" -X PUT http://localhost:8080/rest/admin/provisioning/application-properties?passphrase=12345678 --data-binary @modified.properties.xml

Users import/export - /rest/admin/provisioning/users 

This API enables the import and export of users and roles.

Resource Verb Description Parameters

/rest/admin/provisioning/users

GET Export users and roles includeUsers Optional, default is true. Specifies whether users should be exported.
includeRoles Optional, default is true. Specifies whether roles should be exported.
PUT Import users and roles importDate Date of the import (ISO8601 format), optional default is the current time.

Examples:

# Export users
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/provisioning/users > users.xml


# Import users
curl -s -S -u <username:password> -H "Content-type: application/octet-stream" -X PUT http://localhost:8080/rest/admin/provisioning/users?importDate=2018-10-12T00:00:00.000 --data-binary @users.xml

Technical administration

License management - /rest/admin/licences 

This API enables you to to list, add, and remove licences files that are located in the <node directory>/lib/licences directory.

Resource Verb Description
/rest/admin/licences

GET

Lists all installed licence files.

/rest/admin/licences/{licenceFileName} PUT

Uploads a new licence file.

DELETE Deletes a licence file.

Examples:

# List installed licences files
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/licences


# Uploaded a licence file
curl -s -S -u <username:password> -H "Content-type: application/octet-stream" -X PUT http://localhost:8080/rest/admin/licences/my.licence --data-binary @my.licence


# Delete a licence file
curl -s -S -u <username:password> -H "Content-type: application/json" -X DELETE http://localhost:8080/rest/admin/licences/my.licence

Dynamic properties management - /rest/admin/properties/overrides 

This API enables you to manage dynamic properties overrides. Dynamic properties can be changed during the node execution with no node restart required for the new value to be taken into account.

Reminder:  Dynamic properties overrides are temporary. They are cancelled when the node is next restarted. You must still update the <node directory>/conf/platform.properties to persist the new values across node restarts.



Resource Verb Description
/rest/admin/properties/overrides

GET

Lists all dynamic properties overrides (Map of key and value).

/rest/admin/properties/overrides/{propertyKeyName} GET

Gets the override value for the property specified in the URL. Returns null if this property is not overridden.

PUT Adds or updates a value override for the property key specified in the URL.
DELETE Removes the value override for the property key specified in the URL. Does nothing if no override was specified.

Examples:

# List current overrides
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/properties/overrides

# Get current override for com.systar.carbon.dataservices.limitedResultNumber
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/properties/overrides/com.systar.carbon.dataservices.limitedResultNumber

# Set current override for com.systar.carbon.dataservices.limitedResultNumber to 10
curl -s -S -u <username:password> -H "Content-type: application/json" -X PUT http://localhost:8080/rest/admin/properties/overrides/com.systar.carbon.dataservices.limitedResultNumber -d 10

# Reset override of com.systar.carbon.dataservices.limitedResultNumber
curl -s -S -u <username:password> -H "Content-type: application/json" -X DELETE http://localhost:8080/rest/admin/properties/overrides/com.systar.carbon.dataservices.limitedResultNumber

Checkpoints management - /rest/admin/checkpoints 

This API enables you to manage checkpoints. This involves listing, creating, locking and unlocking checkpoints.

Resource Verb Description Parameters
/rest/admin/checkpoints

GET

List all existing checkpoints with the following information :

  • transaction time,
  • comment,
  • lock state.

PUT

Create a new locked checkpoint

comment A description explaining the checkpoint creation
/rest/admin/checkpoints/{transactionTime} PUT Lock/Unlock the checkpoint specified by the transaction time in the URL action

The action to execute:

  • lock
  • unlock

Examples:

# List checkpoints
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/checkpoints

# Create a checkpoint
curl -s -S -u <username:password> -H "Content-type: application/json" -X PUT http://localhost:8080/rest/admin/checkpoints?comment=Test%20checkpoint

# Lock a checkpoint
curl -s -S -u <username:password> -H "Content-type: application/json" -X PUT http://localhost:8080/rest/admin/checkpoints/1655267012215046145?action=lock

# Unlock a checkpoint
curl -s -S -u <username:password> -H "Content-type: application/json" -X PUT http://localhost:8080/rest/admin/checkpoints/1655267012215046145?action=unlock

Active recomputing period - /rest/admin/computing/activeRecomputingPeriod 

This API enables you to manage the active recomputing period. This option is described in Computing options.

Resource Verb Description Parameters
/rest/admin/computing/activeRecomputingPeriod

GET

Get the current value for the active recomputing period
PUT

Set the value for the active recomputing period

periodDuration

The value for the active recomputing period.
Here are how to format the value:

  • A positive integer with duration type separated by a space.
    The allowed duration types are: hours, minutes and days.
    If the value equals 0 then it will be interpreted as the current duration type.
    Ex:
    • 10 hours : recomputing will be triggered if updates happened within the last 10 hours
    • 0 days : recomputing will be triggered if updates happened on the current day
  • Never : recomputing are never triggered by updates

Examples:

# Get Active recomputing period
curl -s -S -u <username:password> -X GET http://localhost:8080/rest/admin/computing/activeRecomputingPeriod

# Set to current hour
curl -s -S -u <username:password> -X PUT http://localhost:8080/rest/admin/computing/activeRecomputingPeriod?periodDuration=0%20hours

# Set to 2 days
curl -s -S -u <username:password> -X PUT http://localhost:8080/rest/admin/computing/activeRecomputingPeriod?periodDuration=2%20days

# Set to Never
curl -s -S -u <username:password> -X PUT http://localhost:8080/rest/admin/computing/activeRecomputingPeriod?periodDuration=Never

Data integration

Routes management - /rest/admin/routes 

This API enables you to to list, start, stop and kill  data integration routes.

Resource Verb Description  Parameters            
/rest/admin/routes

GET

Lists all routes that are located in a space the user has access.

For each route the following information are returned : 

  • UUID
  • space key
  • name
  • status : STOPPED, STARTED, STOPPING, STARTING or KILLING 
  • starting policy : MANUAL or AUTOMATIC
  • errorMessage : if the route has a configuration issue


/rest/admin/routes/{spaceKey} GET List all routes of the specified space.

/rest/admin/routes/{spaceKey}/{routeName} GET Get information on the specified route.

/rest/admin/routes/{spaceKey}/{routeName} PUT Initiate an action on the specified route
action

  • start
  • stop
  • kill 
    (only for routes stuck in STOPPING status)

Examples:

# Lists all routes that are located in a space the user has access.
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/routes

# Lists all routes of the space 'integration".
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/routes/integration

# Get information of the route 'loadDefinition"in the space'integration".
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/routes/integration/loadDefinition

# Starts the route 'loadDefinition" in the space'integration".
curl -s -S -u <username:password> -H "Content-type: application/json" -X PUT http://localhost:8080/rest/admin/routes/integration/loadDefinition?action=start

Connectors management - /rest/admin/connectors 

This API enables you to to list, refresh data integration connector. The user must have the right to use system integration to be able to use this API.

Resource Verb Description  Parameters            
/rest/admin/connectors

GET

Lists all connectors that are located in spaces the user has access to.

For each connector the following information are returned : 

  • UUID
  • space key
  • name




/rest/admin/connectors/{spaceKey} GET List all connectors of the specified space if the user can access it. 
/rest/admin/connectors/{spaceKey}/{connectorName} PUT Initiate an action on the specified connector
action
  • refresh

Examples:

# Lists all connectors that are located in spaces the user has access to.
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/connectors

# Lists all connectors that are in space 'integration' assuming the user has access to it.
curl -s -S -u <username:password> -H "Content-type: application/json" -X GET http://localhost:8080/rest/admin/connectors/integration

# Refresh the connector 'dims_integration" in the space'integration".
curl -s -S -u <username:password> -H "Content-type: application/json" -X PUT http://localhost:8080/rest/admin/connectors/integration/dims_integration?action=refresh

Notifications management - /rest/admin/notifications 

This API enables you to to list notifications with their start status or get the status of a specific notification. It enables also to perform some actions on it. The user must have the application's permission  notification to be able to use this API.

Resource Verb Description  Parameters            
/rest/admin/notifications

GET

Lists all notifications

For each connector the following information are returned : 

  • name
  • status
  • last error message




/rest/admin/notifications/{notificationName} GET Get the information about a specific notification 
/rest/admin/notifications/{notificationName} PUT Initiate an action on the specified notification
action
  • start
  • stop

Examples:

# Lists all notifications
curl -s -S -u <username:password> -H  "Content-type: application/json"   -X GET http: //localhost :8080 /rest/admin/notifications
 
# Get information about the notification 'notificationSample'
curl -s -S -u <username:password> -H  "Content-type: application/json"   -X GET http: //localhost :8080 /rest/admin/notifications/notificationSample
 
# Start the notification named 'notificationSample'
curl -s -S -u <username:password> -H  "Content-type: application/json"   -X PUT  http://localhost:8080/rest/admin/notifications/notificationSample?action=start


# Stop the notification named 'notificationSample'
curl -s -S -u <username:password> -H  "Content-type: application/json"   -X PUT http://localhost:8080/rest/admin/notifications/notificationSample?action=stop

Access token API

Other API use access token because it can be used at node start-up, before users and roles are actually loaded from database.

HA

At HA node start, or if the main node fails, an operator (the cluster manager) is in charge of switching backup and main roles.

A REST API is provided to control HA status. It is secured by an access token in the header (specified by the property com.systar.electron.ha.token).

Resource Verb Description Parameters

/rest/ha/status

GET Get HA status

-


POST Change HA status change

New status.

Allowed values :

  • MAIN
  • BACKUP

When HA node switches from backup to main, it resumes last main's work with less that 2 minutes of data reprocess.

When HA node switches from main to backup, the node is killed (return code = 0).
The cluster manager needs to restart the node after this operation. Alternatively, the DI nodes can be installed as a service with automatic restart configuration.

Examples:

# Read status
curl -H "Authorization: token myAccessToken" -X GET http://node2host:8080/rest/ha/status
BACKUP

 
# Change status
curl -H "Authorization: token myAccessToken" -X POST http://node2host:8080/rest/ha/status?change=MAIN

# Read status again
curl -H "Authorization: token myAccessToken" -X GET http://node2host:8080/rest/ha/status
MAIN

See Switch backup to main for more details and examples.

Related Links