Toggle menu

Remote API Servers

Sometimes you'll need your website and iCM, both hosted in the GOSS Datacentre, to communicate and interact with various back-office systems, hosted either by yourself or a third party.

Direct Access via a VPN

Our preferred method for connecting the platform hosted with us to non-hosted systems is via a VPN. This would allow the GOSS-hosted services to communicate directly with your environment.

This approach means simpler API Server configuration, developers having less to consider when writing End Points, and gives your infrastructure team control over what can be accessed.

Remote API Server

We no longer recommend remote API Servers due to the fact they still require VPN connections and add extra complications in setup, support and maintenance.

A remote API Server is an API Server service installed in the non-GOSS environment, linked to the GOSS platform via a VPN, through which communication between the platform and external system passes. The remote service hosts some API Workers of its own, and proxies requests to others back to the GOSS hosted platform.

The configuration and initial setup of the API Servers is more complicated than direct access. Our ability to support and monitor the remote API Server will also be limited (see below). As communication is handled by the single API Server it can also become a single point of failure.

Configuring a Remote API Server

The following diagram shows a typical remote API Server installation.

Remote API Server and VPN

The things to note are:

  • Not all workers are shown, the GOSS-hosted API Server would typically contain many more
  • HTTP requests are made in both directions over the VPN, using the standard API Server port 5706
  • There is no direct access to the iCM database over the VPN
  • If the remote API Server is running any End Point capable workers, it must have the iCM API worker defined as a proxy

Typically only the workers needed for the integration should be deployed to the remote API Server.

Proxied Workers

The proxied workers on the remote API Server can be invoked locally using http://localhost:5706. The API Server will automatically proxy the request to the corresponding worker in the GOSS-hosted environment. This includes requests made by End Points deployed to the remotelibrary.

End Points

In the example above the Server Library is running on both API Severs. This means that any End Points published to this worker are available locally in both environments.

The Remote Library is only running on the remote server. End Points published to it are available locally on the remote server. They can be invoked from the GOSS-hosted environment by making a direct request to http://remotehost:5706/remotelibrary.

Configuration

Remote API Severs are managed from within the System Configuration section of iCM Management, in exactly the same way as any other API Server. Their configuration script should be held in the standard icm\custom\apiserverconfigs directory.

Each proxied worker should have the following configuration, entered as an object in the "proxies" array:

{
    "proxies": [{
        "name": "<<worker_name>> Proxy",
        "pathRegex": "^/<<worker_URL>>",
        "targetHostReplacementPattern": "http://<<GOSS_server_host>>:5706",
        "servicePaths": [{
            "name": "<<worker_name>>",
            "urlPath": "<<worker_URL>>"
        }],
        "apiKey": "<<generated_API_key>>"
    }]
}

Where:

<<worker_name>> The name of the worker you'd like to proxy
<<worker_URL>> The URL of the worker, eg "^/auth"
<<GOSS_server_host>> The IP/hostname of the server you would like to proxy requests to (eg the local API server of the GOSS-hosted iCM)
<<generated_API_key>> See below

The workers you need to proxy should be bound to an API key. This key can be restricted using IP rules to only allow requests that originate from the VPN.

This screenshot shows a dedicated key for the remote API Server and the workers we are planning to proxy.

Remote API Server Key

Example Setup Steps

Once an API Server has been installed remotely, the following steps should be carried out.

  1. Make a note of the local API Server's hostname/IP, visible in the iCM/API Servers section of iCM
  2. In the API Server Security section, add both the local server's and remote server's IP addresses to the MANAGER key (as allowed IPs)
  3. In the API Server Security section, create a new API key. Add each worker you would like to proxy to this key. Add the IP address of the remote server as an allowed IP. Make a note of the key
  4. Create a new remote API Server .conf file. Add every worker you would like to proxy to it, plus the workers you would like to run on the remote server. An example file is shown below
  5. In the iCM/API servers section, create a new API Server. Enter the host and URL of the remote server and choose the remote config file created in the previous step
  6. Save the server and send the configuration to it

Example Configuration File

In the example below, substitute GOSSHostedApiServer with the address of your GOSS environment, and add the key your proxied workers are bound to to apiKey.

{
    "proxies": [
    {
        "name": "gatekeeper Proxy",
        "pathRegex": "^/gk",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "gatekeeper", "urlPath": "gk"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "icmapi Proxy",
        "pathRegex": "^/icmapi",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "icmapi", "urlPath": "icmapi"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "formutils Proxy",
        "pathRegex": "^/formutils",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "formutils", "urlPath": "formutils"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "workflow Proxy",
        "pathRegex": "^/workflow",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "workflow", "urlPath": "workflow"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "formsservice Proxy",
        "pathRegex": "^/formsservice",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "formsservice", "urlPath": "formsservice"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "filestore Proxy",
        "pathRegex": "^/filestore",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "filestore", "urlPath": "filestore"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "email Proxy",
        "pathRegex": "^/email",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "email", "urlPath": "email"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    },
    {
        "name": "history Proxy",
        "pathRegex": "^/history",
        "targetHostReplacementPattern": "http://GOSSHostedApiServer:5706",
        "servicePaths": [{"name": "history", "urlPath": "history"}],
        "apiKey": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx"
    }
  ],
    "workers" : [
        {
            "name": "remotelibrary",
            "instances": 4
        }
    ]
}

Requesting Services on Remote API Servers

Once remote services have been set up, requests to those services need to include the correct URL. Remember that if you are working remotely, proxied workers are accessible using http://localhost:5706.

Requests to an API Server are most commonly made using the apiclient library. A standard request in an End Point, to a local service, will look something like:

function( params, credentials ) {
    var apiclient = require("apiclient");
    var client = new apiclient.ApiClient({
    });
    var request = client.invoke("service", "method", {"parameters"});
    return request;
}

To make a request to a remote API Server, provide its URL as the server value:

function( params, credentials ) {
    var apiclient = require("apiclient");
    var client = new apiclient.ApiClient({
        server : "http://remoteServer:5706"
    });
    var request = client.invoke("service", "method", {"parameters"});
    return request;
}

Multiple Environments

Where you have development, test, pre-production and production environments hosted with us, we recommend replicating this in the systems you would like to integrate with.

For example, if your production website integrates with a live back-office system, your test environment, to allow thorough testing, should be able to connect to a test version of the system, so that testing can be carried out without the risk of interfering with live data.

Maintenance and Monitoring

The GOSS Network Team are responsible for monitoring and ensuring the availability of the VPN connection. This availability also depends upon the remote/client end of the connection, which is outside of our control.

Remote API Servers are managed from within iCM, so can be maintained by any user with suitable security privileges. The API Server Consoles of remotely installed servers are also accessible from the GOSS-hosted iCM via the standard proxy.

During patches, upgrades, and their initial installation, the API server installer will need to run on the remote server. With sufficient access a member of the GOSS Network Team will be able to do this, or alternatively installation instructions can be provided.

Note that during the initial installation, when first configuring the security of the remote API Server, it may be necessary to access the API Server's installation directory.

We are unable to monitor or guarantee the availability of non-hosted API Servers.

Last modified on 06 September 2021

Share this page

Facebook icon Twitter icon email icon

Print

print icon