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

The following REST services are available in InterPlay:

  • Configuration
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/configuration
  • The following operations are supported on this resource:
    • GET – gets the runtime version of the application
    • PUT – updates the component's configuration to the last version of the application
    • DELETE – cleans the configuration of the component
  • Exports
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/exports
  • The following operation is supported on this resource:
    • POST – A POST request on the Export service URL starts an export documents operation asynchronously . The response of the request contains the URL from where the status of the operation can be retrieved.
  • partialExports
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/partialExports
  • The following operation is supported on this resource:
    • POST – A POST request on the URL starts a partial export documents operation asynchronously . The response of the request contains the URL from where the status of the operation can be retrieved.
  • massImports
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/massImports
  • The following operation is supported on this resource:
    • POST – A POST request on the URL starts an import documents operation asynchronously . The response of the request contains the URL from where the status of the operation can be retrieved.
    • /v1.0/massImports/{taskId} – gets the imports status
  • imports
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/imports
  • The following operation is supported on this resource:
    • POST – A POST request on the URL starts an import document operation asynchronously . The response of the request contains the URL from where the status of the operation can be retrieved.
  • collections
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/collections
    • DELETE- request on this URL starts a purge collection operation asynchronously . The response of the request contains the URL where the status of the operation can be retrieved from.
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/collections/locks
    • DELETE – request on this URL unlocks a list of business collections.
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/collections/status
    • PUT – request on this URL changes status for a list of business collections.
  • sessions
  • Request URL: http://<host>:<port>/interplay-web/api/v1.0/user/sessions
  • The following operation is supported on this resource:
    • GET – request on this URL starts a list of sessions for a given user name.
    • Request URL: http://<host>:<port>/interplay-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>/interplay-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>/interplay-web/api/v1.0/user/sessions/{userName}/{sessionId}

For details about REST services parameters, the InterPlay RESTful API documentation is provided as a Swagger UI that can be found at http://<host>:<port>/interplay-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

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 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.

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:

{

"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": " 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.

Related Links