Version 23.0.9145

• Using the Embedded Server
  • Starting the Application
    • Launching CData API Server as a Standalone Application
    • Launching CData API Server as a Windows Service
  • Hosting TLS/SSL Connections (Embedded Server)
  • Using the Cloud Gateway to Expose CData API Server to the Internet
  • Enabling the Admin API
  • Managing Notifications
• Deploying CData API Server to Microsoft Internet Information Services (IIS)
  • IIS 8, 8.5, and 10
    • Create a New Web Application
    • Configure Permissions
    • Prevent Application Processes from Unloading
    • Configure ASP.NET App Pool Recycling
    • Preloading Applications
    • Confirm Settings
  • IIS 7 and 7.5
    • Create a New Web Application
    • Configure Permission
    • Prevent Application Processes from Unloading
    • Configuring ASP.NET App Pool Recycling
    • Preloading Applications
    • Confirm Settings
  • Hosting TLS/SSL Connections (IIS)
  • Managing Users
    • Manage application Administrators
    • Manage API Users
    • Windows Authentication
  • Troubleshooting
    • The application stops responding some time after I log out.
    • Visiting http://localhost/application results in a “Page Cannot Be Displayed” error (an HTTP 404 error).
    • 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”.
• Upgrading from CData API Server 2022
• Load-Balancing Configuration

The .NET edition of CData API Server comes packaged with a standalone, embedded web server. You also can deploy API Server to Microsoft Internet Information Services (IIS). This page explains how to configure and start the server in the .NET environment.

If you do not have experience with IIS, the embedded server is recommended. The embedded server deploys automatically upon installation. This server provides a simple interface for server-level administration tasks such as configuring logging, running the application as a service, and enabling the Secure Sockets Layer (SSL) security protocol.

Using the Embedded Server

This section explains how to start and configure the standalone, embedded web server, and it provides details about how to host TLS/SSL connections and how to configure the cloud gateway, a reverse secure-shell (SSH) tunnel.

Starting the Application

You can run the API Server application in either of two ways:

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

• Run API Server 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.

Launching CData API Server as a Standalone Application

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

1. Enter Start API Server in the Start search menu and select that entry when is displayed.

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 CData API Server > Launch API Server Admin Console.

   • Open a web browser to the port and address to which the application binds. By default, that address is localhost:8153.

Launching CData API Server as a 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. Enter Start API Server in the Start search menu and select that entry when is displayed.

2. Right-click the API Server icon in the taskbar. Then, select Server Options to open the CData APIServer dialog box.

3. Click the Service tab and 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 you enable the service, use one of these methods to launch the API Server web interface:

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

• Open a web browser to the port and address to which the application binds. By default, that address is localhost:8153.

Managing the Service

After you enable the service, you can manually start, stop, or restart the service, as follows:

1. Enter services in the Start search menu and select Services to launch the Services Management Console.

2. Scroll until you find the service that is named CData APIServer.

   • If the service is running, the Status column should say Running.

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

Hosting TLS/SSL Connections (Embedded Server)

You can require TLS as well as offer services in plaintext. This section explains how to host TLS/SSL connections in the standalone server that is included with the .NET edition of the application.

To host TLS/SSL connections:

1. Right-click the icon for the application in the Windows system tray and click Server Options to open the CData APIServer dialog box.

2. Click the Web Server tab and select Enable TLS. Then, select a port on which to listen for TLS connections.

3. Click the … button next to the TLS Server Certificate box to open the Select a Private Key dialog box.

4. Select a private-key certificate. The certificate with the private key must be installed to the Local Computer certificate store. If no certificates match that criterion, click Create New Certificate to create a simple certificate for this purpose.

5. Click OK to exit the Select a Private Key dialog box.

6. Click Save Changes and then Exit in the CData APIServer dialog box.

After you complete these steps, the server will restart and begin serving TLS requests.

You can manage the certificates that are available in the certificate-selection dialog box from 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 Start search box.

2. Select File > Add/Remove Snap-In.

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

4. Select Computer Account > Local Computer.

5. Click OK.

After you add 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.

To import a certificate from the local disk into this store, select Action > All Tasks > Import. After you complete the steps in the import wizard, the certificates are available in the certificate-selection dialog.

Using the Cloud Gateway to Expose CData API Server to the Internet

The API Server cloud gateway 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, you can access API Server via a port on that SSH server by using an SSH reverse tunnel.

To use this functionality:

1. Right-click the application icon in the system tray and select Server Options. Navigate to the Cloud Gateway tab and enter the following information:

   • Host: Enter the SSH server to which API Server connects.

   • Port: Select the port on which the SSH host listens for connections. Most SSH servers listen on port 22, which is the default value.

   • Authentication Type: Select the type of authentication to use. Supported types are Password, Public Key, Multi-Factor, and Keyboard Interactive.

   • User: Enter the username that API Server uses to authenticate to the SSH server.

   • Password: Enter the password that is used to authenticate (if required) by the Authentication Type that is selected.

   • Certificate: Specify the certificate that API Server uses to authenticate. This field is available only when the authentication type is Public Key.

   • Server Fingerprint: Enter the SSH host key fingerprint for the SSH server. This value is Read-only and is purely informational.

   • Forwarding Port: Select the port on which the publicly available SSH server listens for connections to forward to the API Server.

   In addition, you might need to change the configuration of your SSH server to allow port forwarding. Default SSH server configuration might not always enable port forwarding to non-localhost addresses. For example, if you are 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 SSH-server connection to verify the validity of the information that is provided. If the test is successful, once you restart the application, API Server is accessible via the Forwarding Port on the SSH host. For example, suppose you specify the SSH server My.SSH.Host with a Forwarding Port of 8401. Entering https://My.SSH.Host:8401 in a browser will then forward the communication to the local machine where API Server is running, allowing public access to the server despite it not being accessible directly.

Enabling the Admin API

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

1. Open the www folder in the installation directory (by default, the directory is C:\Program Files\CData\CData API Server).

2. Open the web.config file in a text editor.

3. Modify access permissions, as follows:

   1. Locate the XML element /configuration/location path="admin.rsc"/.

   2. Change the value of the /system.web/authorization/deny users="*"/ element to /system.web/authorization/allow users="*"/.

   3, Make this same change for the /configuration/location path="admin.rst"/ element.

4. Save your changes to the file.

5. Restart API Server.

After you complete these steps, the admin user can access the API Server Admin API at the endpoints admin.rst and admin.rsc.

Note: The Admin API is accessible only to the API user named admin. Access is denied to other API users.

Managing Notifications

You can receive notifications from API Server by email. In addition, you can log error messages to the Windows Application Event log.

To configure API Server so that you receive email notifications:

1. Select Settings > Notifications in the Admin console.

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

3. Set the authentication and security properties for the SMTP server (User, Password, and Encryption Type).

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

To see error messages in the system’s Application Event log, select the checkbox Write error messages to the Windows Application Event Log, which appears in the Windows Application Event Log category (bottom of the Notifications tab).

Deploying CData API Server to Microsoft Internet Information Services (IIS)

Although API Server comes packaged with embedded web server, you can also deploy it to the Microsoft IIS web server. The sections that follow provide the steps you need to accomplish a deployment to IIS. These instructions cover several versions of IIS and Windows. If you have difficulty following these instructions, see Troubleshooting. If your version is not covered in these tutorials or if you have other questions, contact the CData Technical Support.

IIS 8, 8.5, and 10

Create a New Web Application

Note: This example uses the default website.

To host API Server on your website:

1. Open the IIS Manager.

2. Right-click Sites (in the Connections pane) and select Add Application.

3. Enter the following information in the Add Application dialog box that is displayed:

   • Alias - The name for the application (for example, "cdata").

   • Application Pool - The application pool that is associated with the application. This tutorial uses “DefaultAppPool”.

   • Physical Path - The path to the www directory, in the directory where the application is 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 the data folder, located in the installation directory.

To enable access to the application pool that is associated with the application:

1. Right-click the folder and select Properties to open the Properties dialog box.

2. Select Edit > Add on the Security tab.

3. In the Enter the object names to select box, enter IIS AppPool\_Your-Application-Pool (for example, IIS AppPool\DefaultAppPool).

4. 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, as shown in this example:

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

Prevent Application Processes from Unloading

IIS can stop a web application for several reasons (for example, when an idle timeout is exceeded or when IIS determines that the application pool’s resource use is too high). These reasons can stop background tasks from occurring in your application.

To ensure that the application continues running, modify the following settings:

1. Enable the optional Application Initialization feature, as follows:

   For Microsoft Windows Server 2012 R2 and Windows Server 2016

   1. Open Server Manager and select Dashboard > Quick Start > Add Roles and Features. The Add Roles and Features wizard opens.

   2. In the Server Roles step, select Web Server (IIS) > Web Server > Application Development > Application Initialization.

   For Microsoft Windows 8 and Windows 10

   1. Open the Control Panel and select Programs and Features > Turn Windows Features On or Off.

   2. Select Internet Information Services > World Wide Web Services > Application Development Features > Application Initialization.

2. In the IIS Manager, click Application Pools in the Connections pane.

3. In the workspace, right-click the application pool and click Advanced Settings.

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

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

   If you are using IIS 8, 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 the Regular Time Interval property to False.

Configure ASP.NET App Pool Recycling

IIS recycles regularly so that it can clean up the ASP.NET application-pool processes. However, you can schedule recycling during off-peak hours, as follows:

1. In the Recycling section, set the Specific Time property to True.

2. Enter the times that you want to recycle by using the format hh:mm:ss.

Preloading Applications

You can use the preloading feature to run applications before users connect, as follows:

1. In the Connections pane, right-click the web application that is associated with the application and select Manage Application > Advanced Settings.

2. In the Preload Enabled menu, select True.

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

Confirm Settings

To open the application and confirm your settings, navigate to http://localhost/cdata. If you receive any errors, see Troubleshooting.

IIS 7 and 7.5

Create a New Web Application

Note: This example uses the default website.

To host the application on your website:

1. In the IIS Manager, select YourServer > Sites in the Connections pane.

2. Right-click your website and select click Add Application to open the Add Application dialog box.

3. In the dialog box, enter the following information:

   • Alias - The name for the application (for example, "cdata").

   • Application Pool - The application pool that is associated with the application. This tutorial uses “DefaultAppPool”.

   • Physical Path - The path to the www directory, in the directory where the application is 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 the data folder, located in the installation directory.

To enable access to the application-pool identity that is associated with the application:

1. Right-click the folder and select Properties to open the Properties dialog box.

2. Select Edit > Add on the Security tab.

3. In the Enter the object names to select box, enter IIS AppPool\_Your-Application-Pool (for example, IIS AppPool\DefaultAppPool).

4. 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, as shown in this example:

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

Prevent Application Processes from Unloading

IIS can stop a web application for several reasons (for example, when an idle timeout is exceeded or when IIS determines that the application pool’s resource use is too high). These reasons can stop background tasks from occurring in your application.

This version of IIS does not have configuration settings to keep the web application running continuously. 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 API Server runs continuously:

1. Install the Application Initialization extension from the Application Initialization Module for IIS 7.5 download page. feature, as follows:

2. In the IIS Manager, click Application Pools in the Connections pane.

3. In the workspace, right-click the application pool and click Advanced Settings.

4. In the General settings, ensure that the Start Automatically property 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 the Regular Time Interval property 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 <applicationPools> entry, as shown in this 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 application-pool processes. However, you can schedule recycling during off-peak hours, as follows:

1. In the Recycling section, set the Specific Time property to True.

2. Enter the times that you want to recycle by using the format hh:mm:ss.

Preloading Applications

You can use the preloading feature to run applications before users connect, as follows:

1. In your ApplicationHost.config file, add the preloadEnabled attribute to the <application> element that is associated with your 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">
   ...
   

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

Confirm Settings

To open the application and confirm your settings, navigate to http://localhost/cdata. If you receive any errors, see Troubleshooting.

Hosting TLS/SSL Connections (IIS)

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

To host TLS/SSL connections:

1. In IIS Manager, click your website’s node in the Connections pane.

2. Click Bindings in the Actions pane.

3. Click Add and select HTTPS.

4. Choose the server certificate.

If you want to require TLS/SSL, double-click the SSL Settings icon in the workspace while your website’s node is still selected. Select Require SSL and click Apply in the Actions pane.

Managing Users

You can configure API Server administrators and API users 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 you can configure Windows authentication for administrator access to the application.

Manage API Users

You can manage API users in the application administration console by selecting Profile > Security. Auth tokens are used to authenticate users to access APIs. Auth tokens 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 Microsoft Windows authentication allows the administrator to use NT LAN Manager (NTLM) authentication to access the API Server Administration Console. It also allows the API users to access APIs using NTLM authentication. If you use the embedded application, the authentication type is configurable under Web Server in the server options. In IIS, you can enable Windows authentication in the Authentication menu.

Troubleshooting

The section provides solution for several common errors that you might encounter.

The application stops responding some time after I log out.

IIS might be unloading your application after it times out from inactivity. By default, IIS terminates the worker process that is 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 that 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 that keep the web application running continuously. 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 error can happen if ASP.NET is not enabled. To confirm whether ASP.NET is enabled, navigate to http://localhost/cdata/favicon.ico. If this page loads successfully, then ASP.NET is not enabled.

If you are running IIS 7 or later:

1. Select Control Panel > Programs (or Programs and Features) > Turn Windows Features On or Off > Internet Information Services > World Wide Web Services > Application Development Features.

2. Select the check box next to ASP.NET.

If you are using Windows Server 2003:

1. Open the Internet Information Services Manager and expand the local computer node.

2. Select Web Service Extensions > ASP.NET > Allow. (In addition, you might need to follow the steps that are described below for IIS 6 or earlier.)

If you are running IIS 6 or earlier:

1. From a Windows command prompt, change to the directory where the .NET Framework version is installed (for example, navigate to C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727).

   Note: You might need to change Framework to Framework64 in the path above if you are using a 64-bit processor.

2. Submit the aspnet_regiis -i command. 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).
   

3. 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. Follow the instructions below for your version of IIS to resolve this problem.

• IIS 8 and 8.5

  First, determine the version of the ASP.NET Common Language Runtime (CLR) component that is used by your application pool. You 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 pane. The .NET CLR Version property is displayed in the list of application pools.

  Then, select the appropriate version of ASP.NET, dependent on your server:

  Microsoft Windows Server 2012

  1. Open Server Manager and select Dashboard > Quick Start > Add roles and features. This selection opens the Add Roles and Features wizard.

  2. In the wizard, select Web Server (IIS) > Web Server > Application Development. Then, select the appropriate version of ASP.NET.

  Microsoft Windows 8

  1. From the Control Panel, select Programs and Features > Turn Windows Features On or Off. This selection opens the Turn Windows Features On or Off dialog box.

  2. In the dialog box, select 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:

  1. In the Control Panel, select Programs and Features > Turn Windows Features On or Off. This selection opens the Turn Windows Features On or Off dialog box.

  2. In the dialog box, select Internet Information Services > World Wide Web Services > Application Development Features > ASP.NET.

  In Windows Server 2008:

  1. Open Server Manager and click Add Role Services.

  2. Select Web Server > Application Development > ASP.NET.

Upgrading from CData API Server 2022

API Server 2023 functions as a drop-in upgrade to API Server 2022. Simply running the installer for API Server 2023 upgrades all necessary application resources.

The installer for API Server 2023 attempts to detect existing installations of API Server 2022 and preserves the connections, users, and settings from the existing installation. If API Server 2022 is not installed in the default location, you might need to point the API Server 2023 installer to the folder on disk where API Server 2022 is installed.

You can install API Server 2023 separately from API Server 2022 by directing the API Server 2023 installer to a different folder than the one in which API Server 2022 is installed. Installations do not interfere with each other so long as they are installed in 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, you can save the settings to a database instead of being strictly file-based. This allows several instances of the API Server to share configurations that are located in a remote database. This functionality 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 that you have created in API Server.

• The AppUsers connection contains the login information for the API users.

• The AppLogs connection records all the information about requests that are made to API Server, which can be useful if you have to troubleshoot any issues.

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.