Set Up a New Aternity REST API Server

The Aternity REST API Server is a component in Aternity on-premise which allows authorized users to send REST API queries to directly extract and analyze Aternity's data without accessing Aternity's dashboards. You can combine the data with other data sources if needed, or transform it as required, then view it in Microsoft Excel, Power BI, or your own data application.
Tip

This component is optional. Add this to your Aternity deployment if you want REST API functionality. If you do not add it to your deployment, this functionality would not be available.

Set up the Aternity REST API Server

To set up this server, run the Python script, which uses a properties file and a Docker image file. You must customize the properties file before running the setup, to provide the correct addresses of your existing Aternity v10 components.

When completed, you can access REST APIs with the URL you defined in external_url, like http://odata-aternity.company.com:80/

Before you begin

  • Download the latest Aternity on-premise's main setup package from the Riverbed support site by selecting Software (size).

  • Complete setting up the Aternity Oracle Database Server.

  • Complete setting up one or more Aternity Vertica Database Servers.

  • Complete setting up the Aternity Dashboard Server and the set up of the Dashboard Gateway.

  • Complete setting up the Aternity Management Server.

  • (Optional) Complete setting up a dedicated Aternity Data Warehouse Server computer.

  • Complete setting up the Aternity ETL Server.

  • (Aternity 10.0.1 only) If the Aternity Management Server uses a certificate which you self-signed, you need to place the self-signature credentials (trust store) somewhere on this computer. Later you enter the trust store's pathname as one of the parameters in the setup.

  • Check that this server conforms to the minimum system requirements:

    Attribute Requirement

    Hardware

    Hardware specifications depend on the size of your Aternity on-premise deployment. Choose the sizing and hardware specifications for your deployment size.

    In addition, check the ports which you must open on this server (learn more).

    Network

    Ensure this server has a static IP v4 address, and that you open the required ports.

    Operating system for Aternity REST API Server or Aternity Data Source for Portal

    • Linux CentOS 7.3 - 7.5 + kernel update version 4.2 or later. To verify your version of CentOS, enter cat /etc/centos-release.

    • (Aternity 10.0.1) Red Hat Enterprise Linux (RHEL) 7.4 or 7.5.

      (Aternity 10.0) Red Hat Enterprise Linux (RHEL) 7.4.

      To verify the RHEL version, enter cat /etc/redhat-release

    • Linux Ubuntu 16.04 (Xenial) LTS (long term support). To verify the Ubuntu version, enter cat /etc/*release

    It must have Python 2.7 or later.

    Docker for Aternity REST API Server or Aternity Data Source for Portal

    Aternity REST API Server or Aternity Data Source must use Docker for Ubuntu or Docker for CentOS (Docker 17.0.3 or 17.06). Learn more. For Red Hat Enterprise Linux (RHEL), use the Docker which comes with RHEL (Docker 1.12 or 1.13).

    After you set up the Docker engine, you can set up the Aternity REST API Server or Aternity Data Source for Portal from a Docker image file.

    Permissions

    Run the setup as a user with root or sudo root privileges on the computer. To verify, enter sudo id.

    Separately, at the end of this setup, you can confirm that the Aternity REST API Server is functioning properly, using a command called verify. To perform verify you must enter an Aternity username and password which has the role: OData Role.

    Time zone

    Synchronize all Aternity components to have the same date, time AND time zone.
Tip

The setup checks free disk space under the logs directory (/var/log). If you are short on disk space for the setup directory, you can map this directory (soft link) to a different drive.

Procedure

  1. Step 1 Access the computer of the Aternity REST API Server.

    Run the setup as a user with root or sudo root privileges on the computer. To verify, enter sudo id.

  2. Step 2 Select the Aternity REST API Server setup package, AOdata_<version>.tar, which you downloaded as part of the Aternity on-premise server setup package.

    Copy it to a temporary location on this computer.

  3. Step 3 Extract the contents of the .tar file by entering: 
    tar -xvf AOData_<version>.tar
    Extract the setup package
    Field Description
    -x

    Use -x to unzip the contents of the package.
    -v

    Use -v to output all messages (verbose).
    -f

    Use -f to specify the filename.
    View the contents of the setup package

    The package contains:

    • aodata_ServiceInstallProperties_<version>.ini is the parameters file for the Aternity REST API Server, which you must edit before running the setup.

    • aodata_<version>.docker is the Docker image file containing the Aternity REST API Server.

    • aodata_ServiceInstall_<version>.py is the Python setup script for the Aternity REST API Server.

  4. Step 4 Edit the .ini file with a plain text editor to configure the following properties: 
    [aternity]

host=<Aternity_Management_Server_IP_or_hostname>
prefix=<http or https>

[oracle]

//This value is encrypted during setup if you set "encrypt_jdbc_urls" to true
oracle_jdbc_url=jdbc:oracle:thin:<Oracle_schema>/<Oracle_pswd>@//<Oracle_IP_or_host>:<Oracle_port>/<Oracle_service_name>

[aodata]

external_url=<http/https>://<hostname>[:external_port]/
listening_port=60080

[system]

change_docker_to_auto_start=true
encrypt_jdbc_urls=true
trust_store_location=<pathname_and_file_of_self-signing_credentials>
    Parameter Description

    host

    Enter the Aternity Management Server’s hostname or FQDN (recommended) or IP v4 address. For example, host=aternity.mycompany.com

    prefix

    Enter http, or https if you set up secured access to Aternity.

    For example, prefix=https

    oracle_jdbc_url

    Enter the connection URL to the Aternity Oracle Database Server, in the format of jdbc:oracle:thin:<Oracle_schema>/<Oracle_pswd>@//<Oracle_IP/host>:<Oracle_port>/<Oracle_service_name>.

    For example, oracle_jdbc_url=jdbc:oracle:thin:aternity/aternity@//oracle.mycompany.com:1521/aternity

    It includes:

    • The protocol, which must always be jdbc:oracle:thin at the beginning.

    • Oracle schema (username) and password to access the Aternity database schema.

      Important

      This MUST be identical to the Aternity schema and password on the Oracle Database Server.

    • Oracle Database Server's hostname or FQDN (recommended) or IP v4 address, like oracle.mycompany.com.

    • Port number to access the Oracle Database Server, like 1521.

    • Service name of the Oracle database, like aternity.

    external_url

    Enter the URL and port for users to access REST API queries. Enter either the FQDN of this machine, or if it is behind a proxy or load balancer, enter the external address of that proxy, which you use to access this machine.

    For example, external_url=http://odata-aternity.company.com:80/

    Tip

    The port inside this URL is the external listening port, which may be different than the listening_port if the machine is located behind a load balancer or proxy server.

    listening_port

    Enter the port number which this machine opens to listen for incoming traffic, if it is different from the predefined value, 60080.

    For example, listening_port=60081

    Typically this is the same as the port in the external_url. However, if this server is behind a proxy server, configure the proxy to point to this listening_port number.

    change_docker_to_auto_start

    Enter true (default value) to automatically start the server on reboot (recommended). If you already start the server manually, and you want to continue starting it manually, change this to false.

    For example, the server starts automatically if you set change_docker_to_auto_start=true

    encrypt_jdbc_urls

    Enter true (default value) to instruct the setup to automatically edit this file and encrypt all the JDBC connection strings.

    For example, if you set encrypt_jdbc_urls=true, setup would edit this file to change the line oracle_jdbc_url=jdbc:oracle:thin:aternity/aternity@//oracle.mycompany.com:1521/aternity into something like oracle_jdbc_url=encrypted4pM5U2iH24tK48l6UJkV056A==ZgUNCsaqLaVdf+d3a+JHKPxC0KUsuDkkVs+2RT
    trust_store_location

    (Optional, only for Aternity 10.0.1, only if you have a self-signed certificate on the Aternity Management Server) Enter the pathname and filename to the Java keystore file (usually a .jks file).

    When this server connects to the Management Server, it needs the certificate there to communicate, and attempts to authenticate its signature. If that certificate is self-signed, you need to provide the credentials yourself in JKS format (learn more).
  5. Step 5 Run the Python setup script by entering the following command: 
    python AOData_ServiceInstall_<version>.py
    Tip

    Type the Python version available on your server (must be 2.7 or later). For example, if you are installing on Ubuntu, the command would be python3 AOData_ServiceInstall_<version>.py

    This may take several minutes to complete. Wait for the setup to complete, with the message INFO: Installation succeeded.

    Run the setup script using Python
  6. Step 6 Verify that the REST API Server responds to queries by going to <external_URL_from_ini_file>/admin/verify. Include HTTP or HTTPS in the URL according to the value of external_url.

    To perform verify you must enter an Aternity username and password which has the role: OData Role.

    View the response to your verification request

    For errors, check the log file at <setup_directory>/ServiceInstaller.log.