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). HTTP is used by default. You can enable HTTPS using the sslEnabled parameter in the INI file of the Automation Engine (ucsrv.ini). If you enable TLS/SSL, make sure that the required certificates are in place. In this case, you use the same certificate you used for the Java communication process (JCP). You have to make sure it is configured correctly, so that the REST API can reach the REST process.

More information:

For additional information about the different certificate types and examples of how they could be created and used, see What Kind of Certificates Should I Use for Automic Automation v21.

Important! Please note that these are only examples, not a requirement for Automic Automation and they are not meant to replace the product documentation.

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:

  • All timestamp values are returned as saved in the database and are not converted by the Automation Engine. The REST client is in charge of any conversion.

  • The Automation Engine does not check if a time zone object exists when executing an object. The AE REST API does not check it either.

  • When you use AE authentication and you import a User object, the User is locked. It must be unlocked in Client 0 and a new password must be set. This behavior does not apply when using LDAP authentication. For more information, see Authenticating Login Data via LDAP and/or LDAP Sync.

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 installation of the REST process is relevant for the AE REST API and for the advanced object search. You can install a single REST process. In this case, all REST requests are sent to this single AE REST API instance and no REST API is available if the REST process is down. For more information, see Installing the REST Process.

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

Important! When using multiple REST processes, it is imperative that each one uses its own Automation Engine configuration file ucsrv.ini. If only one INI file is used for more than one REST process, 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 REST process stating the reason for termination.

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

Chart of proxy configuration of clustered JCPs.

To use this configuration, a REST process 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 REST nodes run 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 REST processes 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 availability of the REST processes. Depending on the result, the HTTP/HTTPS proxy knows which REST process is available at the moment.

  • In a High Availability active/active setting, both are intended to be available.
  • In a High Availability active/passive setting, only one of them is intended to be available.

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

  • In a High Availability active/active setting, it sends it to one of both available. Which one is used depends on the selecting strategy of the proxy (for example, lowest load or connections).
  • In a High Availability active/passive setting, it sends it to the one that is available.

Health Check Requests

The AE REST API provides two different health checks:

  • a fast /ping request to be used by HTTP/HTTPS proxies to ensure that the REST node is available. This health check does not provide any details on the required backend components:

    ../ping

  • a system information health check which provides details on the REST node. This health check also provides details on the required backend components:

    ../{client}/system/health

For more information, see AE REST API - Health Check.

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 supports password obfuscation using the UCYBCRYP.EXE that is supplied by default in your installation. It is recommended to use HTTPS to secure the transmission of this information. For more information, see Obfuscating 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.

  • To retrieve variables, comments, and reports of an execution (GET) you need the authorization S - Executions.

  • To add comments to an execution (POST), you need the authorization M - Modify at runtime.

For more information, see Granting Automation Engine Authorizations.

Tracing

All REST activities can be traced for analysis purposes. To do so select a REST process 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:

  • 0: Tracing disabled
  • 1: Traces REST headers and content
  • 2: Traces also login information

Web Server Configuration

The Automation Engine REST node 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:

  • Cross-Origin Resource Sharing / Same Origin Policy (CORS/SOP)

    • corsSupportEnabled

    • corsAccessControlAllowOrigin

  • GZIP Compression

    • gzipSupportEnable

  • ThreadPool

    • minPoolSize

    • maxPoolSize

    • idleTimeout

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.

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 node 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:

  • corsSupportEnabled=1
  • corsAccessControlAllowOrigin=http://host1:80

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 node 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 REST node 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 REST process.

See also: