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.

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.

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

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

All REST services can be tested using the Swagger UI.

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

}

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, the Designer RESTful API documentation is provided as a Swagger UI that can be found at http://<host>:<port>/designer-web/apidocs.

All REST services can be tested using the Swagger UI.

Administration REST services

The following REST services are available for Administration:

  • 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 injecting data into Datastore, 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": "http://localhost:8080/dsclient-web/storage/ap.IEvent_Trace_S1",

"collectionTypeName": "AUDIT_COLLECTION",

"collectionTypeVersion": "1",

"dsComponentName": "DatastoreRuntime"

"responseUri": "http://<host>:<port>/<path>/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"

]

}

}

}

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

Related Links