Search

Windows Edition

Version 22.0.8500

Windows Edition

The Windows version of the application comes packaged with a stand-alone embedded web server, and you can also host the server in IIS. This page outlines how to configure and start the server on Windows.

If you do not have experience with IIS, the embedded server is recommended. The embedded server is automatically deployed at installation and provides a simple interface for server-level administration tasks such as configuring logging, running the application as a service, and enabling SSL.

Embedded Server

This section shows how to configure the stand-alone, embedded Web server, including how to Host TLS/SSL Connections and configure the Cloud Gateway, a reverse SSH tunnel.

Starting the Application

There are two ways to run API Server:

  • As a standalone application without the Windows service. This is how you launch API Server the first time after installation. You can also continue to use this method if you do not want to install the Windows service.

  • As a Windows service, which requires you to enable the service feature. This method makes it easier and quicker to access the API Server interface.

Standalone Application

Follow these steps to launch API Server as a standalone application without the Windows service:

  1. Open the start menu and type Start API Server. Select it when it appears.

  2. Use one of these methods to launch the Web interface for the application:

    • Double-click the API Server icon in the system tray.

    • Right-click the API Server icon and select Start Application.

    • Open the start menu and select Launch API Server Admin Console.

    • Open a web browser to the port and address that the application binds to (by default, localhost:8153).

Windows Service

You can use the API Server Windows service to simplify the process of launching and accessing the application.

Enabling the Service

Follow these steps to enable the service:

  1. Open the start menu and type Start API Server. Select it when it appears.

  2. Right-click the API Server icon in the taskbar and select Server Options.

  3. On the Service tab, select Run as a Windows Service.

  4. Click Save Changes.

Note: You only need to enable the service once. After you restart your machine, the service remains enabled unless you manually disable it.

Launching the Application

After enabling the service, use one of these methods to launch the Web interface for the application:

  • Open the start menu and select Launch API Server Admin Console.

  • Open a web browser to the port and address that the application binds to (by default, localhost:8153).

Managing the Service

After enabling the service, you can manually start, stop, or restart the service by following these steps:

  1. Open the start menu and type services. Select the Services application that appears to launch the Services Management Console.

  2. Scroll down to the service called CData APIServer.

    • If it is running, the Status column says Running.

    • You can right-click the service to access options to Start, Stop, and Restart it.

Hosting TLS/SSL Connections (Embedded Server)

You can require TLS as well as offer services in plaintext. This section shows how to host TLS/SSL connections in the stand-alone server included with the Windows edition of the application. To deploy TLS/SSL for the Java edition, refer to the documentation for the Java servlet you are using to host the application.

  1. Right-click the icon for the application in the Windows system tray and click Server Options.

  2. On the Web Server tab, select Enable TLS and select a port that you want to listen on for TLS connections.

  3. Click the button next to the TLS Server Certificate box to select a private key certificate. The certificate with private key must be installed to the Local Computer certificate store. If there are no certificates available that match that criteria, click Create New Certificate to create a simple certificate for this purpose.

The server will restart and begin serving TLS requests after you save your changes.

Managing Personal Certificates

If you would like to manage the certificates that are available in the certificate selection dialog, they are located in the Personal certificate store for the local computer. To add a certificate to the Windows store:

  1. Launch Microsoft Management Console by entering mmc from the Run menu.
  2. Click File > Add/Remove Snap-In.

  3. Select Certificates from the Available Snap-Ins table and click Add.

  4. Select Computer Account > Local Computer.
  5. After adding the snap-in, click Certificates (Local Computer) > Personal > Certificates to display the available certificates. The certificates for which a private key is available have a small key icon superimposed over the certificate icon.
  6. To import a certificate from the local disk into this store, click Action > All Tasks > Import. After completing the import wizard, the certificates are available in the application certificate selection dialog.

Cloud Gateway

The Cloud Gateway feature of the API Server provides a simple way to expose the application to the Internet without the need for firewall changes. As long as a publicly accessible SSH server is available, the API Server may be accessed via a port on the publicly accessible SSH server by leveraging an SSH Reverse Tunnel.

To leverage this functionality, right-click the application icon in the system tray and select Server Options. Navigate to the Cloud Gateway tab, as shown below, and enter the following information:

  • Host indicates the SSH server that the API Server connects to.
  • Port indicates the port on which the SSH host is listening for connections. Most SSH servers listen on port 22, which is the default value.
  • Authentication Type indicates the type of authentication to use. Password, Public Key, Multi-Factor, and Keyboard Interactive are supported.
  • User indicates the username the API Server uses to authenticate to the SSH server.
  • Password indicates the password used to authenticate, if required, by the Authentication Type used.
  • Certificate indicates the certificate the API Server uses to authenticate to the SSH server during Public Key Authentication.
  • Server Fingerprint indicates the SSH host key fingerprint of the SSH server. This value is read-only and purely informational.
  • Forwarding Port indicates the port that the publicly available SSH server listens on for connections to forward to the API Server.

In addition, it may be necessary to change the configuration of your SSH Server to allow port forwarding. Default SSH server configuration may not always enable port forwarding to non-localhost addresses. For example, if connecting to an OpenSSH server, the GatewayPorts property must be set to yes or clientspecified in the SSH server configuration file.

After you enter this information, click Test Connection to test the connection to the SSH server to verify the validity of the information provided. If successful, once the application is restarted, the API Server is accessible via the Forwarding Port on the SSH host. For example, if the SSH server my.ssh.host was specified, with a Forwarding Port of 8401, entering https://my.ssh.host:8401 in a browser would cause the communication to be forwarded to the local machine where the API Server is running, allowing public access despite it not being directly accessible.

Enabling Management API (Admin API)

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

  1. Open the www folder in the install directory (by default, C:\Program Files\CData\CData API Server).
  2. Open the web.config file in a text editor.
  3. Modify access permissions:
    • Navigate to the XML element /configuration/location path="admin.rsc"/.
    • Change the value of the /system.web/authorization/deny users="*"/ element to /system.web/authorization/allow users="*"/.
    • Make this same change for the /configuration/location path="admin.rst"/ element.
  4. Save your changes to the file.
  5. 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.

Managing Notifications

To configure notifications, open the Settings page in the admin console and select Notifications. You can receive notifications about the API Server by email, and you can log any error messages to the Windows Application Event log.

Email

To configure settings and authentication for the SMTP outgoing mail server, specify the From, To, and Subject settings for the emails and set the authentication and security properties for the SMTP server.

Application Event Log

API Server can write errors to the system’s Application Event Log. You can turn on this setting by selecting Write error messages to the Windows Application Event Log.

Configuration in IIS

These instructions cover several versions of IIS and Windows. If you run into difficulties following one of these guides, see the last section, Troubleshooting. If your version is not covered in this tutorial or if you have other questions, contact our support team for further assistance.

IIS 8, 8.5, and 10

Create a New Web Application

Note: This example uses the default website.

To host the application on your website:

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application.
  3. In the Add Application dialog that is displayed, enter the following information:
Alias The name for the application; for example, “cdata”.
Application Pool The application pool associated with the application. This tutorial uses “DefaultAppPool”.
Physical Path The path to the www directory, in the directory where the application was installed. The default location for this directory is C:\Program Files\CData\CData API Server\www.
Configure Permissions

The application must be able to access the www folder and data folder, located in the installation directory. Allow access to the application pool associated with the application:

  1. Right-click the folder and click Properties. On the Security tab, click Edit > Add.
  2. In the Enter the object names to select box, enter the following: IIS AppPool\your-application-pool. For example, enter IIS AppPool\DefaultAppPool.

  3. Ensure that the application pool has the following permissions:

    • Read
    • Write
    • Modify
    • Read & Execute
    • List Folder Contents

Note: You can also use the command line to allow access to the application pool. For example:

icacls "www" /grant "IIS APPPOOL\\DefaultAppPool":(OI)(M)

Prevent Application Processes from Unloading

IIS can shut down a web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool’s resource use is too high. This may halt background tasks from occurring in your application. Ensure that the application stays running by modifying the following settings:

  1. Enable the optional Application Initialization feature.

    In Windows Server 2012 R2 and Windows Server 2016, open Server Manager and click Dashboard > Quick Start > Add Roles and Features. The Add Roles and Features wizard opens. In the Server Roles step, click Web Server (IIS) > Web Server > Application Development > Application Initialization.

    In Windows 8 and Windows 10, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > Application Initialization.

  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the workspace, right-click the application pool and click Advanced Settings.

  4. In the General settings, set Start Mode to AlwaysRunning.

  5. In the Process Model settings, set the Idle Timeout property to 0.

    If you are using IIS 8, to ensure that the Start Automatically property in the General settings is set to True.

  6. In the CPU section, set the LimitInterval property to 0.
  7. In the Recycling section, set the Regular Time Interval property to 0.
  8. In the Generate Recycle Event Log Entry node, under the Recycling section, set Regular Time Interval to False.
Configure ASP.NET App Pool Recycling

IIS recycles regularly so that it can clean up the ASP.NET app pool processes. You can instead schedule recycling during off-peak hours by navigating to the Recycling section, and setting Specific Time to True and enter the times to recycle in the format hh:mm:ss.

Preloading Applications

You can use the preloading feature to have applications running before users connect. In the Connections pane, right-click the Web application associated with the application and click Manage Application > Advanced Settings. In the Preload Enabled menu, select True.

When PreloadEnabled is set to True, IIS simulates a user request to the default page of the website or virtual directory so that the application initializes.

Confirm Settings

To open the application, navigate to http://localhost/cdata. If you are getting any errors, see Troubleshooting.

IIS 7 and 7.5

Create a New Web Application

To host the application on your website.

Note: This example uses the default website.

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application.
  3. In the Add Application dialog that is displayed, enter the following information:
Alias The name for the application; for example, “cdata”.
Application Pool The application pool associated with the application. This tutorial uses “DefaultAppPool”.
Physical Path The path to the www directory, in the directory where the application was installed. The default location for this directory is C:\Program Files\CData\CData API Server\www.
Configure Permission

The application must be able to access the www folder and data folder, located in the installation directory. Allow access to the application pool identity associated with the application:

  1. Right-click the folder and click Properties. On the Security tab, click Edit -> Add.
  2. In the Enter the object names to select box, enter the following: IIS AppPool\your-application-pool. For example, IIS AppPool\DefaultAppPool.

  3. Ensure that the application pool has the following permissions:

    • Modify
    • Read & Execute
    • List Folder Contents
    • Read
    • Write

Note: You can also use the command line to allow access to the application pool. For example:

icacls "www" /grant "IIS APPPOOL\\DefaultAppPool":(OI)(M)

Prevent Application Processes from Unloading

IIS can shut down a web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool’s resource use is too high. This may halt background tasks from occurring.

This version of IIS does not have configuration settings to always keep the Web application running. To ensure that the application pool is always running so that background tasks will occur, you need to configure a script to issue an HTTP request to the application periodically.

In IIS 7.5, you can ensure that the application stays running by modifying the following settings:

  1. Install the Application Initialization Extension for IIS 7.5. You can download it at http://www.iis.net/download/ApplicationInitialization.
  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the workspace, right-click the application pool and click Advanced Settings.
  4. In the General settings, ensure that Start Automatically is set to True.
  5. In the Process Model settings, set the Idle Timeout property to 0.
  6. In the CPU section, set the LimitInterval property to 0.
  7. In the Recycling section, set the Regular Time Interval property to 0.
  8. In the Generate Recycle Event Log Entry node, under the Recycling section, set Regular Time Interval to False.
  9. Modify the settings for the application pool entry in the ApplicationHost.config file, located in C:\Windows\System32\inetsrv\config\. Add startMode=”AlwaysRunning” and autoStart=”True” to the appropriate entry. For example:
<applicationPools>
<add name="DefaultAppPool" managedRuntimeVersion="v4.0" startMode="AlwaysRunning" autoStart="true"/>
</applicationPools>
Configuring ASP.NET App Pool Recycling

IIS recycles regularly so that it can clean up the ASP.NET app pool processes. You can instead schedule recycling during off-peak hours by navigating to the Recycling section, and setting Specific Time to True and enter the times to recycle in the format hh:mm:ss.

Preloading Applications

You can make use of the preloading feature to have applications running before users connect. In your ApplicationHost.config, add the preloadEnabled attribute to the element associated with the application. The application node is a child element of the sites node, as shown in the following example:

<sites>
  <site name="Default Web Site" id="1">
  <application path="/cdata" applicationPool="DefaultAppPool"  preloadEnabled="true">
  ...

When PreloadEnabled is set to true, IIS simulates a user request to the default page of the website or virtual directory so that the application initializes.

Confirm Settings

To open the application, navigate to http://localhost/cdata. If you are getting any errors, see Troubleshooting.

Host TLS/SSL Connections (IIS)

TLS/SSL can be used to protect the confidentiality of your business-critical and mission-critical communications with trading partners. The following steps assume you already have a certificate you can use to enable TLS/SSL on your server.

  1. In IIS Manager, click your website’s node from the Connections pane.
  2. Click Bindings on the Actions pane.
  3. Click Add and select HTTPS.
  4. Choose the server certificate.
  5. If you want to require TLS/SSL, double-click the SSL Settings icon in the workspace with your website’s node still selected. Select Require SSL and click Apply in the Actions pane.

User Management

API Server administrators and API users can be configured in ASP.NET.

Manage application Administrators

You can use standard ASP.NET configuration settings to configure application administrators. Forms authentication is enabled by default, but Windows authentication can be configured for administrator access to the application.

Manage API Users

You can manage API users in the application administration console by clicking Profile -> Security. Authtokens are used to authenticate users to access APIs. Authtokens uniquely identify an authorized user and represent the level of permissions for the user.

If you want to use ASP.NET to control access to the resources of the application, remove control from the application. To do so, delete the api:restrict element in the api.rsc file in the www subfolder, as shown in the following example:

<api:restrict user="admin"/>
Windows Authentication

Enabling Windows authentication allows the administrator to use NTLM authentication to access the API Server administration console. It also allows the API users to access APIs using NTLM authentication. If using the embedded application, the authentication type is configurable under Web Server in the Server Options. In IIS, Windows authentication can be enabled in the Authentication menu.

Troubleshooting

The sections below provide resolutions for several common errors.

The application stops responding some time after I log out.

IIS is possibly unloading your application after it times out from inactivity. By default, IIS terminates the worker process assigned to the application after 20 minutes of inactivity. The section “Prevent Application Processes from Unloading”, in the steps to set up your version of IIS, explains how to override this feature.

In IIS 7.5, 8, and 8.5, you can ensure the application stays running by modifying the configuration settings in the IIS Manager.

Versions of IIS before IIS 7.5 do not have configuration settings to always keep the web application running. To ensure that the application pool is always running so that background tasks occur, you need to configure a script to issue an HTTP request to the application periodically.

Visiting http://localhost/application results in a “Page Cannot Be Displayed” error (an HTTP 404 error).

This can happen if ASP.NET is not enabled. To confirm if ASP.NET is enabled, go to http://localhost/cdata/favicon.ico. If this page loads successfully, then ASP.NET is not enabled.

If you are running IIS7 or higher, select Control Panel > Programs (or Programs and Features) > Turn Windows Features On or Off > Internet Information Services > World Wide Web Services > Application Development Features. Select the check box next to ASP.NET.

If you are using Windows Server 2003 open the Internet Information Services Manager, expand the local computer node, and click Web Service Extensions > ASP.NET > Allow. You may also need to follow the steps below.

If you are running IIS 6 or earlier open the Windows command prompt, navigate to the .NET Framework version installation, such as C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727, and issue the aspnet_regiis -i</b> command. You may have to change Framework to Framework64 if you are using a 64-bit processor. The output should resemble the following:

C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727>aspnet\_regiis -i
  Start installing ASP.NET (2.0.50727).
  ...
  Finished installing ASP.NET (2.0.50727).

Restart IIS by issuing the iisreset command. The output should resemble the following:

  C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727>iisreset

  Attempting stop...
  Internet services successfully stopped
  Attempting start...
  Internet services successfully restarted

The section is locked at a parent level. Locking is either by default (overrideModeDefault=”Deny”), or set explicitly by a location tag with overrideMode=”Deny” or the legacy allowOverride=”false”.

This error can occur if ASP.NET is not installed.

  • IIS 8 and 8.5

First, determine the version of the ASP.NET CLR that is used by your application pool. You will need to install the version of ASP.NET that ships the same ASP.NET CLR. For example, ASP.NET 4.5 uses CLR version 4.0. You can find the CLR version in the IIS Manager by clicking Application Pools in the Connections panel. The .NET CLR Version property is displayed in the list of application pools.

In Windows Server 2012, open Server Manager and click Dashboard > Quick Start > Add roles and features. The Add Roles and Features wizard opens. Click Web Server (IIS) > Web Server > Application Development and select the appropriate version of ASP.NET.

In Windows 8, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > Application Development and select the appropriate version of ASP.NET.

  • IIS 7 and 7.5

In Windows 7, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > ASP.NET.

In Windows Server 2008, open Server Manager and click Add Role Services. Select Web Server > Application Development > ASP.NET.

Upgrading From API Server 2021

API Server 2022 functions as a drop-in upgrade to API Server 2021; simply running the installer for API Server 2022 will upgrade all necessary application resources.

The installer for API Server 2022 will attempt to detect existing installations of API Server 2021 and preserve the connections, users and settings from the existing installation. If API Server 2021 was not installed in the default location, it may be necessary to point the API Server 2022 installer to the folder on disk where API Server 2021 was installed.

API Server 2022 can be installed separately from API Server 2021 by directing the API Server 2022 installer to a different folder than the one in which API Server 2021 was installed. Installations will not interfere with each other so long as they are installed to different folders.

Load-Balancing Configuration

To set up a load-balancing configuration, the multiple instances of the application must use a synchronized configuration. To do so, the settings can be saved to a database instead of being strictly file-based. This allows several instances of the API Server to share configurations located in a remote database. This is defined in the Web.config file, between the <configuration> tags. The example below shows a potential configuration:

<configuration>
  [...]
  <connectionStrings>
  <add name="AppDB" providerName="System.Data.CData.MySQL" 
    connectionString="Server=myserver;Port=3306;Database=apiserver;User=myUser;Password=myPassword" />
  <add name="AppUsers" providerName="System.Data.CData.MySQL" 
    connectionString="Server=myserver;Port=3306;Database=apiserver;User=myUser;Password=myPassword" />
  <add name="AppLogs" providerName="System.Data.CData.MySQL" 
    connectionString="Server=myserver;Port=3306;Database=apiserver;User=myUser;Password=myPassword" />
  </connectionStrings>
</configuration>

In this example:

  • The first connection, AppDB, contains the application settings and information on the connections you have created in the API Server.
  • The AppUsers connection contains the login information for the API users.
  • The AppLogs connection records all the information on requests made to the API Server, which can be useful when troubleshooting.

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.