Starting the OneDB REST API

About this task

The OneDB REST API is a Java-based mid-tier gateway server that will process HTTP requests from clients. The OneDB REST API is provided as an executable JAR file in the HCL OneDB APIs package.

Table 1. Prerequisites for starting the OneDB REST API:
Java 11
A OneDB server instance that is up and running

To start the OneDB REST API :

Procedure

  1. Create a REST configuration file.

    Sample yaml configuration file:

    # REST port number
    port: 8080
    
    # List of database servers that the REST API can connect to 
    onedb.servers:
      - 
        alias: server1
        host: host1.mycompany.com
        port: 9088
      -
        alias: server2
        host: host2.mycompany.com
        port: 9088
                  
    # Optional, but recommended, properties to enable HTTPS
    tls.enable: true
    tls.keystore.type: pkcs12
    tls.keystore.file: rest-keystore.pkcs12
    tls.keystore.password: myPassword
    
    # Optional, but recommended, property to enable anti-CSRF tokens
    security.csrf.token.enable: true
    The onedb.servers property is required. This specifies the alias, host, and port number for the databases servers that HTTP clients will be able to access through the REST API.
    Important: In addition to onedb.servers, it is recommended that you configure the TLS (HTTPS) and anti-CSRF configuration properties in order to secure your REST API when running it in a production environment. See the Securing the REST API topic for more information on how to properly secure your REST API server.

    The REST API uses HTTP Basic Authentication. The REST server will connect to the OneDB database server through JDBC using the provided user and password credentials provided by the HTTP client.

  2. Start the REST listener using Java 11 or higher
    java -jar onedb-rest.jar -config rest-config.yaml

    where rest-config.yaml is the name of your REST configuration file.