Search

Java Edition

Version 22.0.8500

Java Edition

You can configure and run the Java Edition of API Server using several server options:

  • The embedded Jetty-based server

  • An external Jetty server

  • An external Tomcat server

Each option is outlined below.

Embedded Jetty Server

API Server comes bundled with a Web server that is built on top of Jetty, which is ideal for most deployment scenarios. CData recommends using this embedded Jetty server unless your setup requires an alternative configuration.

Starting the Application

You can start the application using the methods outlined below.

Using a Java Command

Open a terminal to the API Server installation directory. Issue a Java command to run the apiserver.jar file, as shown in the following example:

java -jar apiserver.jar

Using the Linux Service

If you install the API Server service on a Linux platform, you can use the terminal to issue start, stop, and restart commands, as shown in the following example:

systemctl [start | stop | restart] cdata-apiserver

Accessing the Admin Console

By default, the embedded server hosts the API Server on port 8080 and only accepts plaintext connections (HTTP and not HTTPS).

After starting the server, access the admin console by opening a web browser to http://localhost:8080. The default username/password credentials to access the UI are admin/admin.

Configuring the Application

The configuration for this Web server is contained within webapp/apiserver.xml, which may be modified to suit your deployment. Some examples of modifications are provided in the contents of apiserver.xml within the XML comments, but any valid jetty.xml configuration should be accepted.

Changing the Port

To configure the port that the embedded server listens on, find the apiserver.xml file in the installation directory. Find the definition of the HTTP connector:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition, modify the following line to change the configured port:

<Set name="port">8080</Set>

Enabling SSL/TLS

To enable SSL/TLS connections (HTTPS), you also need to modify the apiserver.xml file in the installation directory as follows.

  1. Find the definition of the HTTP connector:

     <New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

  2. Within this definition (as a direct child of the above <New> element in step 1), supply an sslContextFactory argument by adding the following XML block:

         <Arg name="sslContextFactory">
        <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server">
           <Set name="KeyStorePath"><SystemProperty name="apiserver.home" default="." />/keystore</Set>
           <Set name="KeyStorePassword">mypassword</Set>
        </New>
     </Arg>

Note: The <Arg> element that is shown above must be adjacent to other <Arg> elements at the beginning of the connector definition. This block must not be placed after the <Set> element that defines the server port, for example.

The KeyStorePath property defines the location of the SSL/TLS certificate that is used when hosting the SSL/TLS server. The previous example assumes that a Java keystore file named keystore is created in the API Server data directory (by default, in C:\ProgramData\CData\apiserver). The KeyStorePassword property should be set to the password that corresponds to the configured certificate.

In addition, you can reference a private key via a PFX file by using an additional key reference with a password, as shown in the following example:

<Arg name="sslContextFactory">
  <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath"><SystemProperty name="apiserver.home" default="."/>mycertificate.pfx</Set>
    <Set name="KeyStorePassword">mypassword</Set>
    <Set name="KeyStoreType">PKCS12</Set>
  </New>
</Arg>

Note: If you obtain an external private key for configuration in API Server, be sure to change the owner of the certificate to the service account that is used to host API Server.

Changing User Credentials

The users that can log into the API Server web UI are defined in the ‘apiserverRealm.properties’ file in the installation directory. Each line in this file defines a user, with the following syntax:

username:password\[roles\]

Add a new line to define new users, or modify the existing line to change the default login credentials.

Setting Up Load-Balancing Configuration

To set up a load-balancing configuration in the embedded Jetty server, you must ensure that the following items are kept in sync:

  • The API Server application file (apiserver.war)
  • JDBC drivers used to connect to your data sources

Jetty configuration files are not directly accessible. Instead, you can configure the custom database resource in the WebAppContext element of the apiserver.xml file located in the webapp\ subdirectory of the installation location. The example below shows this configuration:

<WebAppContext>
  <Call name="setHandler">
    <Arg>
      <New id="apiserver" class="org.eclipse.jetty.webapp.WebAppContext">
        [...]
        <Call name="setInitParameter">
          <Arg>APP_DB</Arg>
          <Arg>jdbc:mysql:Server=my_server;Port=3306;Database=my_database;User=my_user;Password=my_password</Arg>
        </Call>
        <Call name="setInitParameter">
          <Arg>APP_USERS</Arg>
          <Arg>jdbc:mysql:Server=my_server;Port=3306;Database=my_database;User=my_user;Password=my_password</Arg>
        </Call>
        <Call name="setInitParameter">
          <Arg>APP_LOGS</Arg>
          <Arg>jdbc:mysql:Server=my_server;Port=3306;Database=my_database;User=my_user;Password=my_password</Arg>
        </Call>
      </New>
    </Arg>
  </Call>
</WebAppContext>

If the base URL of the API Server does not correspond to the server where the API Server is installed, you may need to manually configure the base URL. To do so, follow these steps:

  1. Log in to the API Server as an admin.
  2. Navigate to Settings > Server.
  3. In the OData section, enter your desired URL in the Base URL field.

When URLs referencing the API Server are generated, such as metadata URLs, they will point to this custom base URL.

Enabling Management API (Admin API)

The Admin API is not enabled by default. To manually enable it, follow these steps:

  1. Open the WEB-INF/web.xml file in a text editor of your choice.

  2. Navigate to the security-constraint section with the display name Restrict direct access to the Management API and change this line:

     <auth-constraint/>

    To this:

     <auth-constraint>
 <role-name>cdata_admin</role-name>
 </auth-constraint>
  3. Save your changes to the file.
  4. Restart the API server.

The API Server Admin API can now be accessed at the endpoint admin.rst (documentation) and admin.rsc by the admin user.

Note: The Admin API is only accessible to the API user named admin. Other API users will be denied access.

AWS AMI

The AWS AMI for API Server uses Java/Jetty. To enable the Admin API in this environment, use the same directions as above. The web.xml file is location at the path:

/opt/apiserver/work/jetty-0.0.0.0-8443-apiserver.war-_-any-/webapp/WEB-INF/web.xml

To restart the API Server service, use this command:

systemctl restart jetty

Managing Notifications

To configure notifications, open the Settings page in the admin console and select Notifications. To receive notifications about the API Server by email, configure the From, To, and Subject settings for the emails and set the authentication and security properties for the SMTP server.

External Jetty Server

While the API Server comes with an embedded Jetty web server, the application can also be used with an external Jetty setup.

Deploying the WAR File

Copy the WAR file into Jetty’s webapps folder.

Allowing Access to Jetty Users

Before starting Jetty, allow Jetty users to access the application by assigning the cdata_admin role. For example, you can add this role to the admin user by opening the JETTY_HOME/etc/realm.properties file. The properties for the user are composed of the password, followed by the user’s roles. For example:

admin: test,server-administrator,content-administrator,admin,user,cdata_admin

Configuring the Login Service for the Java Realm

You must also configure a login service for the application with the name CDataRealm. Below is a HashLoginService example:

<Call name="addBean">
  <Arg>
    <New class="org.eclipse.jetty.security.HashLoginService">
      <Set name="name">CDataRealm</Set>
      <Set name="config"><Property name="jetty.home" default="."/>/etc/realm.properties</Set>
    </New>
  </Arg>
</Call>

Configuring Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\
  • Unix or Mac OS X: ~/cdata/

Restart the server and log into the application.

Setting Up Load-Balancing Configuration

To set up a load-balancing configuration in an external Jetty server, you must ensure that the following items are kept in sync:

  • The API Server application file (apiserver.war)
  • JDBC drivers used to connect to your data sources

Follow these steps to configure these resources:

  1. Enable the jetty-plus module in $JETTY_HOME/start.ini using the command --module=plus.

  2. Add the open source JDBC MySQL driver to $JETTY_HOME/lib/ext.

  3. Add the following entries to the jetty.xml file:

     <Configure id="Server" class="org.eclipse.jetty.server.Server">
   [...]
   <New Id="AppUsers" class="org.eclipse.jetty.plus.jndi.Resource">
     <Arg></Arg>
     <Arg>jdbc/APP_USERS</Arg>
     <Arg>
       <New class="com.mysql.cj.jdbc.MysqlConnectionPoolDataSource">
         <Set name="url">jdbc:mysql://my_server:3306/my_database</Set>
         <Set name="User">my_username</Set>
         <Set name="Password">my_password</Set>
       </New>
     </Arg>
   </New>
 </Configure>

  4. Add the reference to the newly-added resource to apiserver.xml, located in $JETTY_BASE/work/[app_name]/webapp/WEB-INF/web.xml inside the web-app tags:

     <web-app>
   [...]
   <resource-ref>
     <description>App Security Datasource</description>
     <res-ref-name>jdbc/APP_USERS</res-ref-name>
     <res-type>javax.sql.DataSource</res-type>
     <res-auth>Container</res-auth>
   </resource-ref>
 </web-app>

  5. Restart the Jetty service, and the API Server will use the newly-defined database.

If the base URL of the API Server does not correspond to the server where the API Server is installed, you may need to manually configure the base URL. To do so, follow these steps:

  1. Log in to the API Server as an admin.
  2. Navigate to Settings > Server.
  3. In the OData section, enter your desired URL in the Base URL field.

When URLs referencing the API Server are generated, such as metadata URLs, they will point to this custom base URL.

Tomcat Server

You can follow these steps to install the application to Tomcat.

Deploying the WAR File

There are two options for deploying a WAR file to Tomcat:

  • Copy the WAR file into the webapps folder.
  • Deploy the WAR file from within the management console in Tomcat. The Tomcat documentation covers this method in more detail.

It is possible that the WAR file may exceed the default maximum size allowed for file uploads in Tomcat. To overcome errors during deployment, you can edit the WEB.XML file of the manager application to allow larger files. Depending on your tomcat configuration, this file may be located in /usr/share/tomcat7-admin/manager/WEB-INF or in a similar directory. In this file, you can change the size (in bits) of the maximum allowed file size. For example, to allow deployment of a 200MB WAR file, edit the following values to change the maximum allowed file size:

<multipart-config>
	<!-- 200MB max -->
	<max-file-size>209715200</max-file-size>
	<max-request-size>209715200</max-request-size>
	<file-size-threshold>0</file-size-threshold>
</multipart-config>

Allowing Tomcat Users to Access API Server

Assign the cdata_admin role to the user you want to be the administrator of the application. If you are using the default user realm for Tomcat, you can add these roles by editing the tomcat-users.xml file located in CATALINA_BASE/conf/tomcat-users.xml. In the following example, the admin user has been given the necessary roles for administrative access to the application:

<user name="admin" password="admin" roles="cdata_admin,admin-gui,manager-gui,manager-status,manager-script,manager-jmx" />

Configuring Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\CData\\
  • Unix or Mac OS X: ~/cdata/

Note that in certain Linux distributions, some additional kernel security modules like SELinux may disable write access to the Data directory. To enable access, please consult the documentation of the kernel security module.

Restart your Tomcat server for the changes to take effect. You can now log in to the application.

Setting Up Load-Balancing Configuration

To set up a load-balancing configuration in Tomcat, you must ensure that the following items are kept in sync:

  • The API Server application file (apiserver.war)
  • JDBC drivers used to connect to your data sources

In Tomcat, you can define those as resources in your server.xml file, within the <Host> tags. The example below shows this configuration:

<Host>
  <Context path="/apiserver">
    <Resource name="jdbc/APP_USERS" auth="Container" type="javax.sql.DataSource"
      maxActive="100" maxIdle="30" maxWait="10000"
      driverClassName="cdata.jdbc.mysql.MySQLDriver"
      url="jdbc:mysql:Server=myServer;Port=3306;Database=myDB;User=user;Password=pass;"/>
  </Context>
</Host>

An attribute factory may be required in the Resource path, depending on the version of Tomcat you are using. If it is required, the configuration should resemble this example:

<Host>
  <Context path="/apiserver">
    <Resource name="jdbc/APP_USERS" auth="Container" type="javax.sql.DataSource"
      factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
      maxActive="100" maxIdle="30" maxWait="10000"
      driverClassName="cdata.jdbc.mysql.MySQLDriver"
      url="jdbc:mysql:Server=myServer;Port=3306;Database=myDB;User=user;Password=pass;"/>
  </Context>
</Host>

If the base URL of the API Server does not correspond to the server where the API Server is installed, you may need to manually configure the base URL. To do so, follow these steps:

  1. Log in to the API Server as an admin.
  2. Navigate to Settings > Server.
  3. In the OData section, enter your desired URL in the Base URL field.

When URLs referencing the API Server are generated, such as metadata URLs, they will point to this custom base URL.

Managing Users

The Java version of the API Server web application uses forms authentication.

In Java, the user roles and passwords are managed in the Java realm configuration for your web server. Refer to your web server’s documentation from how to configure a user’s roles and password. The application requires the cdata_admin role.