AE REST API - General Info

As a developer or system administrator, you can use the REST API to communicate with the Automation Engine system using a technology-independent, state-of-the-art interface.

This page includes the following:

Overview

The AE REST API provides an interface for third-party applications to interact with the Automation Engine. The AE REST API also allows the user to target the Automation Engine not only from Java, but from many programming languages.

The REST requests and responses contain JSON structured data:

Optional properties with value null might be omitted in the response payload.

The AE REST API supports both HTTP and HTTPS (recommended). HTTPS can be set with the sslEnabled parameter in the Automation Engine configuration file ucsrv.ini. For more information, see HTTPS/SSL set up for AE REST API in Installing the JCP.

The current version of the AE REST API is v1. This information is reflected in the URI and is therefore relevant when accessing your AE REST API interface.

The AE REST API can be installed multiple times. The installation can be either with different port numbers on one node or on different nodes with the same port number.

Notes:

AE REST API and ILM

During the daily operation of an Automation Engine system, large amounts of reporting, statistical, and historical data accumulate. Partitioning the database with ILM is an efficient method to deal with it and maintain the object version and the deleted object data. ILM actions require switching out parts of the Automation Engine database tables; therefore, no database actions should take place while working with ILM. For more information, see ILM - Information Lifecycle Management.

Important! The AE REST web service automatically detects if there are any ongoing ILM actions and, if so, it blocks specific REST requests. In this case, an error message is returned, indicating that the REST API is momentarily not available due to ILM actions.

Localization

REST API messages are by default in English. The AE REST API does not support any other language.

Setting up Multiple REST API Processes

The JCP installation is relevant for the AE REST API and for the advanced object search. You can install a single JCP. In this case, all REST requests are sent to this single AE REST API instance and no REST API is available if the JCP is down. For more information, see Installing the JCP.

You can also set up a system with multiple JCPs. In this case, two JCPs are used in a cluster but only one of both is available at the time.

Important! When using multiple JCPs, it is imperative that each JCP uses its own Automation Engine configuration file ucsrv.ini. If only one INI file is used for more than one JCP, the first one connects successfully while the others terminated upon trying to register the same REST port if both run on the same node. An error message is written to the log file of the JCP stating the reason for termination.

Setting up a system with multiple JCPs can be convenient for balancing and to provide failover capabilities, because the REST requests are sent and distributed only to available JCPs.

Chart of proxy configuration of clustered JCPs.

To use this configuration, a JCP must be installed on each node. Port1 and port2 can have the same port number (for example, 8088, the default value in the configuration file) because the JCPs/REST web services are running on different hosts (host1 and host2). Host3:port3 must be public available as single point of contact for all AE REST API requests. Host1:port1 and host2:port2 must be known only by the HTTP/HTTPS proxy.

If a virtual IP is being used, both JCPs can be reached through the same IP address, which means that the endpoints have the same base URI: http(s)://{host}:{port}/ae/api/v1/{client}/....

The REST client or a HTTP/HTTPS proxy periodically sends a /ping request to check the JCPs availability. Depending on the result, the HTTP/HTTPS proxy knows which JCPs are available at the moment.

The REST client or HTTP/HTTPS then decides where to send the REST requests, depending on the selection strategy of the proxy. When the REST client sends requests to the HTTP/HTTPS proxy (host3:port3), the proxy dispatches them automatically to a JCP/REST web service.

Health Check Requests

The AE REST API provides two different health checks:

Authentication

The AE REST API supports basic authentication. The client, user, department, and password information are part of the HTTP(S) header and of the URI and therefore used for basic authentication. The Automation Engine decides whether a REST request in the user context is allowed or not and responds accordingly.

The request is processed if the client number entered in the authentication information is the same as in the URI. If the client number differs, an error is returned.

The AE REST API does not support password encryption for the password that is stated in the REST request. It is recommended to use HTTPS to secure the transmission of this information. For more information, see Encoding Passwords.

Authorizations

An efficient and secure system to protect the access to data is a key part of our security concept. Security at data level can be as broad as administrator access to a role, or as granular as Read access to only one job in one specific folder. For more information, see Access Control.

The AE REST API also requires certain authorizations to perform different operations and checks if they are in place when performing them.

For more information, see Granting Automation Engine Authorizations.

Generate at Runtime

To avoid request timeouts, the objects to be executed must have the attribute Generate Task at: Runtime set. When executing and object, the system checks if this attribute has been set accordingly. If it has not been set, the execution is not started. For more information, see Attributes Page.

By setting this attribute the RunID is returned immediately, so that the REST response follows the request straightaway.

If this attribute is set to Generate Task at Activation Time, long processing might prevent immediate REST response which may result in a timeout.

Note: When restarting an execution, the attribute Generate Task at Runtime is not set.

AE REST API Polling

You can poll the server to check the status of a REST request/response sequence in case the desired result is not yet available. For example, you could poll the server after executing an object and getting the RunID to check if the execution has ended.

The following sample shows how polling for execution status can be done through the AE REST API:

Input through PromptSet

PromptSet variables can be passed through the AE REST API request on execution given the objects to be executed have at least one PromptSet assigned.

Example of REST request content:

Notes:

Filter for Execution List

The request GET ../v1/{client}/executions returns a list of all executions. You can add query parameters as part of the URI to filter the them.

Note: The Automic Web Interface has different settings for list views that are relevant when applying filters. The hierarchical view, which, when using filters, affects only parent tasks and the list view, which affects both, parent and child tasks. The AE REST API supports only the list view.

You can apply filters for the following execution parameters:

Important! Parameters that allow you to exclude certain properties are only effective in combination with their counterparts.

Example

name and name_exclude

You can combine the query parameters as required to build simple or complex filters. For example, you can:

Pagination for Child Task Executions and Execution Lists

Pagination can be useful if a request to the AE REST API returns numerous results, because the result set, which can change fast and often, is divided into chunks (pages) per request/response. For example, if you send a request to get all the child task executions of a specific execution, thousands of records may be retrieved. In AE REST API, you can use pagination to make results easy to handle.

Limit Parameters

AE REST API allows you to set the following limit parameters:

URI Structure with Pagination Parameters

The URI including the pagination parameters consists of the following elements:

http://{host}:{port}/ae/api/v1/{client}/executions/{runid}/children?max_results={number}&start_at_run_id={runid}

Example

http://192.168.40.116:8088/ae/api/v1/100/executions/1003003/children?max_results=10&start_at_run_id=100301

In this example, the requested parent execution 1003003 has 25 child task executions requested. The paginated response is distributed as follows:

Notes:

Pagination for Reports

Pagination is also useful when a report is rather large and its content is split into report pages. The AE REST API paginates these report pages.

Limit Parameters

Important! The AE REST API can only request the content of reports available in the AE database. A job report is stored in the database only if the Store to: Database option has been selected in the Job Report section of the job definition page. This option is selected by default.

Tracing

All REST activities can be traced for analysis purposes. To do so select a JCP and right-click to select Advanced Options. This action opens a dialog where you can specify trace flags.

The trace flag can also be set in the Automation Engine configuration (INI) file. To do so, set the JCL key in the TRACE section of the INI file. The relevant values for the RA Web Service REST Agent are:

Web Server Configuration

The Automation Engine REST web service uses a web server which largely uses a predefined configuration. As a system administrator, you can customize the parameters that are listed here in [REST] section of the Automation Engine configuration file ucsrv.ini:

CORS/SOP

The Same Origin Policy (SOP) prevents web clients from carrying out cross-origin requests. You can circumvent this policy using Cross-Origin Resource Sharing (CORS) to allow origins explicitly.

For example:

Chart of web server configuration.

Host 3 requests a web document from origin 1 (Host 1, web server) at http://host1:80 (default http port). Host 3 then requests information from origin 2 (Host 2, AE) at http://host2:8080 (default AE REST web service port). The most common web browsers check whether cross domain requests are allowed or not. If not, the request to the second origin http://host2:8080 is not allowed.

To allow such cross origin requests, the AE REST web service must explicitly tell the web browser to allow the request. You can define it using the following CORS parameters in the [REST] section of the Automation Engine configuration file ucsrv.ini:

If the web server runs on the same local host as the browser or web client (Host1 = Host3), you must implement a simple web-based REST client by setting the parameter corsAccessControlAllowOrigin to http://localhost:80.

Compression

A REST client can state in a request that the response payload should be compressed to improve performance. If the REST web service supports compression, it sends back the payload in gzip format.

Compression support is disabled by default. You can enable it using the gzipSupportEnabled parameter in the [REST] section of the Automation Engine configuration file ucsrv.ini.

Thread Pooling

The web server that is used by the JCP/REST web service processes requests with help of threads. The more threads are used, the more REST requests can be processed in parallel.

A thread pool keeps multiple threads waiting to process REST requests. The more requests come in, the more threads the web server automatically makes available within the range that is defined in minPoolSize >= N <= maxPoolSize. If some of the N threads remain unused for a period longer than the timeout period defined in the idleTimeout parameter, these are killed to free resources on the JCP process.

See also: