The REST configuration file

A sample configuration file is provided in the example-rest-config.yaml file. In the sample configuration file, all of the properties are commented out by default. To enable a property, you must uncomment the row and customize the property.

To modify the configuration after the REST API is started, you must first stop the REST server, update the configuration file, and then restart the REST API for the changes to take affect.

REST configuration properties

• REST server configuration
  • hostname
  • port
• OneDB servers
  • onedb.servers
• Security settings
  • security.csrf.token.enable
  • tls.enable
  • tls.keystore.type
  • tls.keystore.file
  • tls.keystore.password
  • tls.pem.cert
  • tls.ciphers
  • tls.protocols
• Timeouts
  • rest.session.timeout
  • metadata.cache.timeout
• Query defaults
  • query.default.limit
  • query.maximumFieldSize
  • query.timeseries.default.limit
• JSON formatting
  • json.format
• JDBC connection pool settings
  • dataSource.IFX_ISOLATION_LEVEL
  • pool.connectionTimeout
  • pool.idleTimeout
  • pool.maximumPoolSize
  • pool.minimumIdle
• TimeSeries loader settings
  • timeseries.loader.flush.interval
  • timeseries.loader.log.level
  • timeseries.loader.put.size.maximum
  • timeseries.loader.session.timeout
• Vert.x configuration options
  • vertx.threads.poolSize

REST server configuration

hostname

This property specifies the hostname for the REST server. The default value of "0.0.0.0" means that the REST API server will listen on all available interfaces.

port

This property specifies the port for the REST server. The default port is 8080.

OneDB servers

onedb.servers

This required property specifies the list of OneDB database servers that the REST API will provide access to. Each database server in the list must have an alias, a hostname, and a port, and can optionally have a set of additional JDBC properties. The alias is specific to the REST API and provides the name you will use in the REST API urls to refer to that particular database server.

onedb.servers:
  - 
    alias: server1
    host: host1.mycompany.com
    port: 9088
  -
    alias: server2
    host: host2.mycompany.com
    port: 9088            
    properties:
        IFX_LOCK_MODE_WAIT: "20"
        IFX_USEPUT: "1"

Security settings

security.csrf.token.enable

This property enables tokens in the REST API to prevent Cross-Site Request Forgery (CSRF) attacks.

When these anti-CSRF tokens are enabled, an X-CSRF-TOKEN will be returned in the header of the first HTTP response for an authenticated session. Any subsequent HTTP POST, PUT, or DELETE request using the same session cookie must include the X-CSRF-TOKEN in the header of the HTTP request. If the X-CSRF-TOKEN is not included in the header or an invalid token is sent, the REST API will respond with a FORBIDDEN response.

It is recommended that you enable these tokens in a production deployment of the REST API. When enabled, REST clients must the X-CSRF-TOKEN in the request header whenever they are using a session cookie to re-use an existing REST session.

tls.enable

This property controls whether TLS is enabled. When enabled, the REST server will be started as an HTTPS server.

tls.keystore.type

This property specifies the keystore type for TLS encryption. Supported values are jks for a Java keystore, pfx or pkcs12 for a PKCS12 keystore, or pem to use PEM files.

tls.keystore.file

This property specifies the path to the keystore file.

tls.keystore.password

This property specifies the password for the keystore file.

tls.pem.cert

This property specifies the path to the PEM certificate, if tls.keystore.type has been specified as pem.

tls.ciphers

This property specifies the list of enabled TLS ciphers. If no value is specified, the JVM's default list of enabled ciphers will be used.

If you are unfamiliar with the Java Cryptography Extension (JCE) and the security implications of the multitude of supported ciphers, you should not specify this property. Consult with a security expert for an up-to-date recommendation based on your use case.

tls.protocols

This property specifies the list of enabled TLS protocols.

tls.protocols:
  - TLSv1.2

Timeouts

rest.session.timeout

This property specifies the number of milliseconds a REST session can be idle before it is closed. The default session timeout is 10 minutes.

metadata.cache.timeout

This property specifies the number of milliseconds that metadata about OneDB databases and tables can remain in the REST API server's cache before they are refreshed. If set to zero, the objects in the cache remain there indefinitely and are only refreshed on an as needed basis.

Query defaults

query.default.limit

This property specifies the default limit for the number of rows returned in a single HTTP query response. Setting this value to -1 indicates that there should be no default limit on the number of rows returned by a query response. The default limit is 100 rows.

query.maximumFieldSize

This property sets a maximum field size for values in relational query results. If a value exceeds the maximum size, it will be truncated. Setting this value to -1 indicates that there should be no limit on the maximum field size.

query.timeseries.default.limit

This property specifies the default limit for the number of TimeSeries entries returned in a single HTTP query response. Setting this value to -1 indicates that there should be no default limit on the number of entries in TimeSeries values within a query response. The default limit is 100 entries.

JSON formatting

json.format

This property specifies the format used for JSON serialization. Allowable values are RELAXED or EXTENDED. The EXTENDED format is compatible with MongoDB's JSON serialization; whereas the RELAXED format is slightly more compact for some data types.

JDBC connection pool settings

dataSource.IFX_ISOLATION_LEVEL

This property specifies the isolation level for JDBC connections. The default isolation level is 1 (DIRTY READ).

pool.connectionTimeout

This property specifies the number of milliseconds to wait for a JDBC connection to a OneDB database server to be established before it times out.

pool.idleTimeout

This property specifies the number of milliseconds that a JDBC connection can be idle in the connection pool before it is closed. The default value is 60000 milliseconds (1 minute).

pool.maximumPoolSize

This property specifies the maximum number of JDBC connections in each connection pool. A connection pool will be established for each unique OneDB server, database, and username that is connected to it through the REST API. The pool.maximumPoolSize property puts a cap on the total number of open JDBC connections that can be established in each one of these connection pools.

pool.minimumIdle

This property specifies the minimum number of idle JDBC connections in each connection pool. A connection pool will be established for each unique OneDB server, database, and username that is connected to it through the REST API. Setting pool.minimumIdle to zero indicates that all JDBC connections in the connection pool should be closed when they exceed the pool.idleTimeout. Setting pool.minimumIdle to a positive integer indicates the number of connections that should be kept open in the connection pool even when they exceed the pool.idleTimeout. The default and recommended value is 0.

TimeSeries Loader settings

timeseries.loader.flush.interval

This property specifies the flush interval, in milliseconds, for the TimeSeries loader.

timeseries.loader.log.level

This property sets the log level used for the TimeSeries Loader stored procedures on the database. This log level effects the level of TimeSeries Loader log messages written to the database server's online.log. Possible values are info, warning, error, and debug.

timeseries.loader.put.size.maximum

This property specifies the maximum buffer size, in bytes, for each TimeSeries Loader put call to the database server.

timeseries.loader.session.timeout

This property specifies the number of milliseconds that a TimeSeries loader session can be idle before it is closed. The default value is 300000 milliseconds (5 minutes).

Vert.x configuration options

vertx.threads.poolSize

This property specifies the maximum number of worker threads in the thread pool used to process HTTP requests.