Version 25.3.9411

• Starting the Application
  • Using a Java Command
  • Using the Linux Service
• Accessing the Admin Console
• Configuring the Application
  • Enabling SSL/TLS
  • Changing User Credentials
• Setting Up a Load-Balancing Configuration
• Enabling the Admin API
• Enabling API Server in the AWS AMI Environment
• Managing Notifications

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

Starting the Application

You can start the application using the methods described in the following sections.

Using a Java Command

To start API Server with a Java command:

1. Open a terminal to the API Server installation directory.

2. Issue the following Java command to run the apiserver.jar file:

   java -jar apiserver.jar
   

Using the Linux Service

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

systemctl [start | stop | restart] cdata-apiserver

Accessing the Admin Console

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

After you start the server, access the admin console by opening a web browser to this URL: http://localhost:8080. To access the UI, use the default username and password credentials (admin/admin).

Configuring the Application

The configuration for the embedded web server is contained within webapp/apiserver.xml, which you can modify to suit your deployment. Some examples of modifications are provided in XML comments within the contents of the apiserver.xml file, but you should accept any valid jetty.xml configuration.

Enabling SSL/TLS

To enable SSL/TLS connections (HTTPS):

1. Open the apiserver.xml file in the installation directory and locate the definition of the HTTP connector that is shown below:

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

2. Within this definition (as a direct child of the <New> element that is shown 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, make sure to change the owner of the certificate to the service account that is used to host API Server.

Changing User Credentials

User accounts (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 a new user or modify the existing line to change the default login credentials.

Setting Up a Load-Balancing Configuration

To set up a load-balancing configuration in the embedded Jetty server, you must ensure that synchronization is maintained for the following items:

• the API Server application file (apiserver.war)

• JDBC drivers that are used to connect to your data sources

You cannot access Jetty configuration files directly. Instead, you can configure the custom database resource in the <WebAppContext> element of the apiserver.xml file that is located in the webapp\ subdirectory of the installation location. The following example shows the <WebAppContext>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=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword</Arg>
        </Call>
        <Call name="setInitParameter">
          <Arg>APP_USERS</Arg>
          <Arg>jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword</Arg>
        </Call>
        <Call name="setInitParameter">
          <Arg>APP_LOGS</Arg>
          <Arg>jdbc:mysql:Server=MyServer;Port=3306;Database=MyDatabase;User=MyUser;Password=MyPassword</Arg>
        </Call>
      </New>
    </Arg>
  </Call>
</WebAppContext>

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

1. Log in to API Server as an administrator (admin).

2. Select Settings > Server.

3. In the OData section on the Server tab, enter the URL that you want in the Base URL text box.

When URLs that reference API Server are generated (for example, metadata URLs), they point to this custom base URL.

Enabling the Admin API

By default, the Admin API is enabled. The admin user can access the API Server Admin API from the admin.rst and admin.rsc endpoints.

Note: The Admin API is accessible only to the API user that is named admin and is limited to enterprise and legacy plans. Access is denied to other API users.

To manually disable the Admin API, follow these steps:

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

2. Navigate to the security-constraint section that is named Restrict direct access to the Management API.

3. Locate the following <auth-constraint> element and remove the entire <role-name> line to delete the role.

    ```xml
    <auth-constraint>
       <role-name>cdata_admin</role-name>
    </auth-constraint>
    ```  
   

4. Save your changes to the file.

5. Restart API Server.

After you complete these steps, the admin user is no longer able to access the API Server Admin API.

Enabling API Server in the AWS AMI Environment

The AWS Amazon Machine Image (AMI) for API Server runs in Jetty, which is a Java servlet container. To enable the Admin API in this environment, follow the same directions that are in the previous section. In this case, the web.xml file is located here:

/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 API Server so that you receive email notifications:

1. Select Settings > Notifications in the Admin console.

2. In the Email Server Settings category, specify values for the From, To, and Subject properties.

3. Set the authentication and security properties for the SMTP server (SMTP Server, User, Password, Port, and TLS Start Mode).

4. Click Send Test Email to verify that you are receiving notifications.