Use REST services

You can use REST services for communication between components. For example at clean/deploy configuration, the Configuration service is used to clean/update the configuration for a component.

InterPlay REST services

This sections lists the REST services available in InterPlay.

For details about REST services parameters, the InterPlay RESTful API documentation can be found at http://<host>:<port>/interplay-web/api/v1/ui.

All REST services can be tested using the Swagger UI at http://<host>:<port>/interplay-web/api/v1/ui or at http://<host>:<port>/interplay-web/swagger-ui.html.

Refer to the Swagger UI for a complete list of available REST services for InterPlay. As an example, here are two of the services available:

  • Configuration
  • Request URL: http://<host>:<port>/interplay-web/api/v1/configuration
  • The following operations are supported on this resource:
    • GET – gets the runtime version of the application
    • PATCH – updates the component's configuration to the last version of the application
    • DELETE – cleans the configuration of the component
  • Change status
  • Request URL:
    • For collections - http://<host>:<port>/interplay-web/api/v1.0/bcollection/status
    • For objects - http://<host>:<port>/interplay-web/api/v1.0/bobject/status
    • For elements - http://<host>:<port>/interplay-web/api/v1.0/belement/status
  • The following operations are supported on this resource:
    • GET – retrieves the status for the items ( unavailable for elements)
    • PATCH – updates the status of the items

Note:

If PassPort is installed, the user must authenticate with a login that has the correct rights to execute REST services:

  • username: PassPort domain/PassPort user
  • password: PassPort password

Datastore REST services

Datastore Client provides RESTful API to allow external systems to send REST calls for various tasks like injecting/extracting data from the database and managing Datastore Runtime components configuration.

For details about REST services parameters, the Datastore Client RESTful API documentation can be found at http://<host>:<port>/dsclient-web/apidocs.

All REST services can be tested using the Swagger UI at http://<host>:<port>/dsclient-web/apidocs/ui.

The following REST services are available for Datastore Client:

  • inject – used to inject data into Datastore.
  • Request URL: http://<host>:<port>/dsclient-web/api/v1.0/inject
  • The following operations are supported on this resource:
    • POST /api/v1.0/inject – inject data into Datastore
    • GET /api/v1.0/inject/{taskId} – get the status of the inject operation
  • extract – used to extract data from Datastore
  • Request URL: http://<host>:<port>/dsclient-web/api/v1.0/extract
  • The following operations are applicable:
    • POST /api/v1.0/extract – extract the result of a query execution into a data file
    • GET /api/v1.0/extract/{taskId} – get the status of the extract operation
  • configurations – used to update / clean the configuration for Datastore components
  • Request URL: http://<host>:<port>/dsclient-web/api/v1.0/configurations/{componentName}
  • The following operations are applicable:
    • PUT – update Datastore component configuration
    • DELETE – clean Datastore component configuration
    • GET – get Datastore component configuration

Note:

If PassPort is installed, the user must authenticate with a login that has the correct rights to execute REST services:

  • username: PassPort domain/PassPort user
  • password: PassPort password

Example for an inject service call

POST request to http://localhost:8080/dsclient-web/api/v1.0/inject with the body:

{

"dataFile": "http://localhost:8080/dsclient-web/storage/ap.IEvent_Trace_S1",

"collectionTypeName": "AUDIT_COLLECTION",

"collectionTypeVersion": "1",

"dsComponentName": "DatastoreRuntime"

}

GET request to http://localhost:8080/dsclient-web/api/v1.0/inject/16953 for the response:

{

"taskId": "16953",

"status": "FINISHED",

"success": true,

"collectionTypeName": "AUDIT_COLLECTION",

"collectionTypeVersion": "1",

"totalTimeMiliSeconds": "595 milliseconds ",

"totalRecordsInjected": "9",

"totalErrors": "0"

}

Example for an extract service call

POST request to http://localhost:8080/dsclient-web/api/v1.0/extract with the body:

{

"queryFullName": "./Query Audit"

}

 

GET request to http://localhost:8080/dsclient-web/api/v1.0/extract/16962 for the response:

{

"taskId": "16962",

"status": "FINISHED",

"success": true,

"file": "/dsclient-web/download/005169635k4mwtwi9v5kjasg2q46r07s4qm61y2",

"totalTimeMiliSeconds": "51 milliseconds ",

"totalErrors": "0",

"totalRecordsExtracted": "708",

"queryName": "./Query Audit"

}

You can find the contents of the file attribute at http://localhost:8080/dsclient-web/download/005169635k4mwtwi9v5kjasg2q46r07s4qm61y2. It can also be sent to other services on the network.

Example for a configurations service call

GET request to http://localhost:8080/dsclient-web/api/v1.0/configurations/DatastoreRuntime for the response:

{

"success": true,

"currentVersion": 49

}

Rule Engine Server REST services

Rule Engine Server provides RESTful API to allow external systems to send REST calls for Rule Engine process operations, and status.

For details about REST services parameters, the Rule Engine Server RESTful API documentation can be found at http://<host>:<port>/resrv-web/apidocs.

All REST services can be tested using the Swagger UI at http://<host>:<port>/interplay-web/apidocs/ui.

The following REST services are available for Rule Engine Server:

  • RuleEngineProcessRest – used to make a Rule Engine process operation.
  • URL: http://<host>:<port>/resrv-web/api/v1.0/process
  • The following operations are supported on this resource:
    • POST /api/v1.0/process – start a Rule Engine process operation
    • GET /api/v1.0/process/{taskId} – get the status of the process operation
  • RuleEngineStatusRest – used to get the status/clean the created Rule Engine Runtimes
  • URL: http://<host>:<port>/dsclient-web/api/v1.0/extract
  • The following operations are supported:
    • POST – clean the created Rule Engine Runtimes
    • GET – get the status of the created Rule Engine Runtimes

Example for RuleEngineProcessRest call

POST request to http://localhost:9081/resrv-web/api/v1.0/process with the body:

{

      "dataFile": "C:\\Axway\\AIS_2.2.0_RC2_R22\\AIS\\Samples\\AIS\\Finance1\\RuleEngine\\data\\IEvent.seq",

      "configurationId": "ais",

      "application": "default",

      "collectionTypeName": "LOAN",

      "collectionTypeVersion": "1"

}

GET request to http://localhost:9081/resrv-web/api/v1.0/process/1 for the response:

{

      "taskId": "1",

      "status": "FINISHED",

      "success": true,

      "collectionName": "LOAN",

      "collectionVersion": "1",

      "reports": [

{

      "name": "dettrans.edi",

      "path": "https://localhost:9081/resrv-web/download/001731ocf3v60imhbibpf746vdojet",

      "type": "DEBUG"

},

{

      "name": "transcnt.edi",

      "path": "https://localhost:9081/resrv-web/download/00186db9epvge2jkri52t5ajoa2ug5",

      "type": "STATISTICS"

},

{

      "name": "cptrg.edi",

      "path": "https://localhost:9081/resrv-web/download/00191a8k4l5oqvqtk412fmqpspsofa",

      "type": "STATISTICS"

},

{

      "name": "detano.edi",

      "path": "https://localhost:9081/resrv-web/download/002104fk0ojhsfkok8l8irkkc1ks631",

      "type": "REJECTS"

}],

      "inputTraceResult": {

      "name": "InputAudit",

      "path": "https://localhost:9081/resrv-web/download/001226098n95o1hr67e27iftqlvbf9",

      "outputType": "INPUT_AUDIT",

      "propertyFile": null

},

      "outputTraceResult": {

      "name": "OutputAudit",

      "path": "https://localhost:9081/resrv-web/download/001154bk2pt1jq0b0sbqjjm1dk9r5a",

      "outputType": "OUTPUT_AUDIT",

      "propertyFile": null

},

      "outputResults": [

{

      "name": "IAS",

      "path": "https://localhost:9081/resrv-web/download/00132qnqe65c4tuej1sj87uev14a6p",

      "outputType": "OUTPUT_EVENT",

      "propertyFile": null

},

{

      "name": "LOCAL",

      "path": "https://localhost:9081/resrv-web/download/0014459henqijnsnae7vgknrttugms",

      "outputType": "OUTPUT_EVENT",

      "propertyFile": null

},

{

      "name": "NULL_FEES",

      "path": "https://localhost:9081/resrv-web/download/00151er1jedkfmvn3fsg4k0ja6kfq0",

      "outputType": "OUTPUT_EVENT",

      "propertyFile": null

},

{

      "name": "SESSION2",

      "path": "https://localhost:9081/resrv-web/download/00165qhlirvdid08qd96sc25du6n0i",

      "outputType": "OUTPUT_EVENT",

      "propertyFile": null

}]

}

The contents of the inputTraceResult can be accessed at https://localhost:9081/resrv-web/download/001226098n95o1hr67e27iftqlvbf9 and it can be sent to Datastore Client for injection.

Example for RuleEngineStatusRest call

GET request to http://localhost:9081/resrv-web/api/v1.0/status for the response:

{

"freeEnginesStatus": [

      {

      "runtimeName": "ARE_1",

      "runtimeState": "CONFIGURED",

      "applicationName": "default",

      "aiConfigId": "aic1",

      "aiConfigVersion": 6

      }

],

"inUseEnginesStatus": [],

"inErrorEnginesStatus": [

      {

      "runtimeName": "ARE_0",

      "runtimeState": "ERR_CONFIG”

      "applicationName": "default",

      "aiConfigId": "aic2",

      "aiConfigVersion": 3

      }

],

"profileName": "",

"processedOperations": 3,

"firstAccess": "2014-09-15 10:05:11",

"lastAccess": "2014-09-15 11:47:32"

}

Designer REST services

The following REST service is available in Designer: Deployment service

Request URL: http://<host>:<port>/designer-web/api/v1.0/deployments

The following operation is supported on this resource:

POST – A POST request on the Deployment service URL creates a deployment package and saves it to <WorkDirectory>/deploymentPackage/. Additionally, it can publish the deployment package to Repository.

For details about REST services parameters, see the Designer RESTful API documentation at http://<host>:<port>/designer-web/apidocs.

All REST services can be tested using the Swagger UI at http://<host>:<port>/designer-web/apidocs/ui.

Administration REST services

All REST services can be tested using the Swagger UI at http://<host>:<port>/aisadmin-web/apidocs/ui.

Refer to the Swagger UI for a complete list of available REST services for Administration. As an example, here are two of the services available:

  • User sessions service:
  • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/user/sessions
  • The following operations are supported on this resource:
    • GET – request on this URL starts a list of sessions for a given user name.
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/user/sessions/{userName}
    • DELETE – request on this URL starts a delete of all sessions for a given user name.
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/user/sessions/{userName}
    • DELETE – request on this URL starts a delete of a session for a given user name and session identifier.
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/user/sessions/{userName}/{sessionId}
  • AI configurations service:
  • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/aiConfigurations
  • The following operations are supported on this resource:
    • POST – used for importing the AI configuration and/or internal tables
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/aiConfigurations/{configurationId}
    • GET – used for listing all the AI configurations and internal tables
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/aiConfigurations
    • GET – user for exporting an AI configuration and/or its internal tables
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/aiConfigurations/{configurationId}
    • DELETE – used for cleaning all the AI configurations and internal tables
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/aiConfigurations
    • DELETE – used for cleaning an AI configuration and/or its internal tables or removing an update for it
    • Request URL: http://<host>:<port>/aisadmin-web/api/v1.0/aiConfigurations/{configurationId}

Polling mechanism

For example, for an Export documents, you must do a POST request to: http://<host>:<port>/interplay-web/api/v1.0/exports. The request format is:

{

"filter": "LIFECYCLE_STATUS=\"2\"",

"status": "To Correct",

"language": "english"

}

The request is processed and the response contains an export task identifier and the URL from where the status of the operation can be retrieved.

{

"taskId": "13",

"resourceURI": "http://<host>:<port>/interplay-web/api/v1.0/exports/13"

}

To check the status, make a GET request to: http://<host>:<port>/interplay-web/api/v1.0/exports/13

If the task is in progress, the response is:

{

"taskId": "13",

"status": "IN_PROGRESS",

"numberOfCollections": 0

}

If the task is finished, the response is:

{

"taskId": "13",

"status": "FINISHED",

"success": true,

"message": "\nINFO The export of the business collection with id 755 successfully ended.\nINFO Change status for the business collection with id 755\nWARN Unable to change businessCollection status: 755\nINFO The number of the exported business collections is 1",

"numberOfCollections": 1,

"fileResults": [

{

"dataFile": "D:\\InterPlay\\work\\output\\2015_03_05_13_14_37_400\\sample"

}

]

}

The path from the response can be used to download the generated files.

For example, for Rule Engine Server file processing, you must do a request to http://<host>:<port>/resrv-web/api/v1.0/process. The request format is:

{

"dataFile": "D:/ais-tools/ruleserver-tools/scanFolder/data/data/IEvent1.seq",

"configurationId": "aic2",

"application": "default",

"collectionTypeName": "LOAN",

"collectionTypeVersion": "1"

}

The request is processed and an asynchronous task is saved in the Repository database. The response contains the task identifier and the url used to check the status of the task. The response is:

{

"taskId": "315166",

"resourceURI": "http://<host>:<port>/resrv-web/api/v1.0/process/315166"

}

The task status can be checked using resourceURI from the response: http://<host>:<port>/resrv-web/api/v1.0/process/315166.

If the task status is IN_PROGRESS, the response is:

{

"taskId": "315166",

"status": "IN_PROGRESS",

"reports": []

}

If the task status is FINISHED, the response is:

{

"taskId": "315166",

"status": "FINISHED",

"success": true,

"reports": [

{

"name": "RuleEngine.log",

"path": "/resrv-web/download/006315174196dvs19ckwwqgql1cjjc0o8znjlvqw",

"type": "DEBUG"

}

],

"collectionVersion": "1",

"reportsGenerated": true,

"outputResults": [

{

"name": "IAS",

"path": "/resrv-web/download/0063151708pvgk7how6iw2ay0k3h9qx1clgbqjaw",

"outputType": "OUTPUT_EVENT",

"propertyFile": null

},

{

"name": "LOCAL",

"path": "/resrv-web/download/006315171ktn9zbog8cufwnr8y6rqlm2rlqilz60",

"outputType": "OUTPUT_EVENT",

"propertyFile": null

},

{

"name": "NULL_FEES",

"path": "/resrv-web/download/006315172hn9j5vil80hpcwbolh9b5ck38aqsl93",

"outputType": "OUTPUT_EVENT",

"propertyFile": null

},

{

"name": "SESSION2",

"path": "/resrv-web/download/006315173nb1vmcnzg1cax3bla15nf3ivohzue42",

"outputType": "OUTPUT_EVENT",

"propertyFile": null

}

],

"inputTraceResult": {

"name": "InputAudit",

"path": "/resrv-web/download/0063151699pqzz07yl790xl2i7316jsrlr1w56h9",

"outputType": "INPUT_AUDIT",

"propertyFile": null

},

"outputTraceResult": {

"name": "OutputAudit",

"path": "/resrv-web/download/0063151682qcy3rteedx1ec0u58krkbvwi03cak6",

"outputType": "OUTPUT_AUDIT",

"propertyFile": null

},

"collectionName": "LOAN"

}

The paths from the response can be used to:

Download the generated files

Send a request to the next component. For example:

{

"dataFile": "http://<host>:<port>/resrv- web/download/0063151682qcy3rteedx1ec0u58krkbvwi03cak6",

"collectionTypeName": "AUDIT_COLLECTION",

"collectionTypeVersion": "1",

"dsComponentName": "DatastoreRuntime"

}

For example, for injecting data into AI Suite, you must do a POST request to http://<host>:<port>/dsclient-web/api/v1.0/inject. The request format is:

{

"dataFile": "http://localhost:8080/dsclient-web/storage/ap.IEvent_Trace_S1",

"collectionTypeName": "AUDIT_COLLECTION",

"collectionTypeVersion": "1"

"dsComponentName": "DatastoreRuntime"

}

The request is processed and an asynchronous task is saved in the Repository database. The response contains the task identifier and the url used to check the status of the task. The response is:

{

"taskId": "315166",

"resourceURI": "http://<host>:<port>/dsclient-web/api/v1.0/inject/315166"

}

The task status can be checked using resourceURI from the response: http://<host>:<port>/dsclient-web/api/v1.0/inject/315166.

If the task status is IN_PROGRESS, the response is:

{

"taskId": "315166",

"status": "IN_PROGRESS",

"reports": []

}

If the task status is FINISHED, the response is:

{

"taskId": "315166",

"status": "FINISHED",

"success": true,

}

Callback URL mechanism

Using the callback URL mechanism, you can set a callback URL in request(responseUri parameter) that is used to send a POST request with the result when the task is finished. The request is:

{

"dataFile": "D:/ais-tools/ruleserver-tools/scanFolder/data/data/IEvent1.seq",

"configurationId": "aic2",

"application": "default",

"collectionTypeName": "LOAN",

"collectionTypeVersion": "1",

"responseUri": "http://<host>:<port>/resrv-web/api/v1.0/processCallbackURL"

}

{

"dataFile": "http://localhost:8080/dsclient-web/storage/ap.IEvent_Trace_S1",

"collectionTypeName": "AUDIT_COLLECTION",

"collectionTypeVersion": "1",

"dsComponentName": "DatastoreRuntime"

"responseUri": "http://<host>:<port>/<path>/processCallbackURL"

}

{

"filter": "LIFECYCLE_STATUS=\"2\"",

"status": "To Correct",

"language": "english",

"responseUri": "http://<host>:<port>/rest/processCallbackURL"

}

Note   In case of a DELETE request, the callback URL can be set in a query string (responseUri) or in the header (X-Response-URI).

Cleanup mechanism

For REST requests that do not specify a destination directory, the generated files, if any, are stored in a temporary directory that is automatically generated . The REST response contains the URLs of the produced files and the client can download them by accessing the URLs.

The client can remove the files after download by performing a DELETE request to the given URLs.

However, if the files are not manually removed, they are automatically cleaned-up after they expire. The generated temporary directories are removed as well when they are empty.

The names of the automatically generated temporary directories follow a specific pattern, specified in Administration > General Settings.

Example of pattern for temporary folders: temp_*_ais. The * character is replaced with the current date and time. In this case, the name of an automatically-generated temporary directory could be: temp_2015_03_14_09_26_53_589_ais.

Rest service response message internationalization

If there is an error for a REST request, the response contains the errorCode parameters, and the message internationalized in the language from the request header. For example:

{

"error": {

"code": "error.inject.dsComponentName.notFound",

"message": {

"lang": "english",

"value": "The component with the name 'DatastoreRuntime' does not exist. ",

"parameters": [

"DatastoreRuntime"

]

}

}

}

{

"error": {

"code": " err.exportDocuments.componentNotRegistered",

"parameters": [

"Interplay"

],

"message": " The component 'InterPlay' is not registered in the repository.",

"level": "ERROR"

}

}

After getting this response, you can either use the internationalized message or internationalize the message using errorCode and parameters.

Rest services scenario

We want to send a REST request to the Rule Engine Server for file processing and then, from the result, we will send the reject files to InterPlay and the audit trace files to Datastore Runtime. We can get the task status in two ways:

  • Using polling mechanism
  • Using callback URL mechanism

Polling mechanism

Pooling mechanism

  1. Send a process REST request to Rule Engine Server.
  2. In response, you get the task identifier and the URL to be used for checking the status of the task.
  3. Check the task status.
  4. When the task is finished, you receive the process result.
  5. Send an import reject files REST request to InterPlay.
  6. In response, you get the task identifier and the URL to be used for checking the status of the task.
  7. Check the task status.
  8. When the task is finished, you receive the import result.
  9. Send an inject audit trace files REST request to Datastore Runtime.
  10. In response, you get the task identifier and the URL to use for checking the status of the task.
  11. Check the task status.
  12. When the task is finished, you receive in response the inject result.

Callback URL mechanism

Callback URL mechanism

  1. Send a process REST request to Rule Engine Server.
  2. The request contains the callback URL used by theRule Engine Server to send back the process file result.
  3. After the process file task is finished, a POST request with the result is performed on callback URL.
  4. Send an import-reject-file REST request to InterPlay.
  5. After the import file task is finished, a POST request with the result is performed on callback URL.
  6. Send an inject-audit-trace-file REST request to Datastore Runtime.
  7. After the import-file task is finished, a POST request with the result is performed on callback URL.

Related Links