Using a proxy and API gateway to optimize Compass for performance

HCL Compass 2.0 introduced a new suite of REST APIs, and a refreshed user interface. This article will explain how these new HCL Compass interfaces are designed to work with proxies and gateways to maximize performance and minimize server load.

1. HCL Compass HTTP resources

The user interface for HCL Compass runs in a browser. Pages are generally composed of two types of resource which are requested from the Compass server by the browser. The first type of resource is JavaScript and style sheets, which controls the layout of the pages, and ultimately renders to HTML, which in turn may contain images. The JavaScript, style sheets and the images are static in nature. Everyone who asks for the same JavaScript, style sheet or image resource gets the same resource, and the resource is unlikely to change while the Compass server is running.

Data, the second type of resource, displayed on the Compass pages is dynamic in nature – different users will see different data even though they are looking at the same ‘page’. For example, a page might display a set of records assigned to me when I look at the page, but when you look at the same page you will see a different set of records assigned to you.

The Compass user interface uses REST APIs to retrieve data from the server. REST APIs are also used whenever the user interface interacts with the server to create, update or delete data.

2. Caching and Throttling

To improve throughput and performance, it may be prudent to cache some resources so that repeated requests for the same resource do not need to go all the way to the Compass server. Static resources make good candidates for caching. Dynamic resources less so.

Where caching is not feasible, consider throttling to prevent your server from being overwhelmed by too many requests. When request submissions exceed the request limit rate, the limit-exceeding requests may fail and return 429 Too Many Requests error responses. Upon catching such exceptions, the client can resubmit the failed requests in a way that is rate limiting.

3. Client server architecture

If your client is a browser, it may implement a caching mechanism so that repeated requests from the same browser for the same resource may be handled by the computer that the browser is running on. The benefit to this caching mechanism is that such cached resources may be retrieved very quickly with no network or server load. Usually two or more users requesting the same resource from two different browsers will result in at least one server-side request for each user.

Another approach is to use a gateway, or proxy between the client and the server. This works well for both browser and non-browser clients. A benefit of using a gateway/proxy as a cache is that two or more users requesting the same resource from two different browsers through the same gateway/proxy will result in just one server-side request for all users.

3.1 Proxy vs API gateway

A proxy is something that acts as an intermediary, making requests on behalf of something else. An API gateway on the other hand, provides a much richer set of capabilities tailored to developers who build backend services. In some case a proxy and a gateway may be two different components. In other cases, a proxy may also be capable of being an API gateway.

A general good practice is to cache static resources using a proxy, and throttle dynamic resources using an API gateway.

3.2 SSL certificates

HCL Compass uses SSL to secure access to its user interface and REST APIs. A self-signed certificate is provided out of the box, but some proxies and gateways will accept self-signed certificates.

Remember to import any custom root certificate you may create into your browser, or operating system’s trust store. This is particularly important if you intend to use a proxy or gateway – the computer running the proxy or gateway will require your root certificate to be installed.

4. Caching

The HCL Compass server implements caching directives that clients (particularly browsers), proxies and gateways can follow to cache resources from the HCL Compass HTTP server.

4.1 HTTP Cache-Control header

Caching directives are passed from the HCL Compass HTTP server to clients using the HTTP Cache-Control header in the HTTP response. Different types of resources have different caching directives.

4.2 User interface resources

HCL Compass enables caching on user interface resources including JavaScript, style sheets and images by specifying a max-age in the Cache-Control header it sends in HTTP responses.

Browsers that support caching will cache these resources automatically. Proxies and gateways can identify these resources easily since they are generally located under the /static path in request URLs.

Note: There are exceptions such as “/favicon.png” and “/” itself which should be marked as cacheable by proxies and gateways.

4.3 APIs

HCL Compass does not enable caching on any REST APIs. The Cache-Control header it sends in HTTP responses specifies no-cache, no-store, max-age=0, must-revalidate. Although some API gateways may allow you to override this, HCL does not recommend caching API calls.

5. Throttling

Unlike with caching, the HTTP protocol does not provide any standard mechanisms for servers to direct clients, proxies or gateways on how to throttle requests, and HCL Compass has not implemented any custom rate limiting HTTP headers.

Proxies and gateways may offer rate limiting between the client and the proxy/gateway, between the proxy/gateway and the HCL Compass server, or both. Depending on the proxy or gateway, rate limits may be applied on a per resource (or API) basis, or globally affecting all resources (and APIs).

HCL has no specific recommendations on which resources (and APIs) to throttle, but generally supports proxy/gateway rate limiting.

6. Example API gateway configuration

Although HCL does not recommend or support any specific proxy or API gateway, there are many fine commercial and open source products out there.

For the purposes of this document, let’s look at an open source API gateway called krakend , which is available from https://www.krakend.io. The API gateway is extremely simple consisting only of an executable file and a configuration file.

Krakend provides an online designer to create and edit configuration files, available at https://designer.krakend.io.

Once downloaded you can start krakend, by simply running krakend -c /path/to/krakend.json.

6.1 Service Configuration

Use the krakend designer to specify the basic service configuration parameters including the backend timeout threshold. Be sure to add the address of the HCL Compass server to the available hosts. Your configuration file should contain something similar to this:

{
 "timeout": "3000s",
 "host": [
  "https://my.gateway.address.com:8080"
 ],
…
}

6,2 Endpoints

6.2.1  Static

HCL Compass’s static resources are generally found under the /static path on the URL. Since these user interface resources are used to render screens on the browser, they are all read-only and are accessed using the HTTP GET method (which is krakend’s default method).

There is no need for a gateway to intercept these resources, so a simple proxy endpoint is all that is required. Krakend treats endpoints whose output_encoding and encoding are no-op as simple proxy endpoints.

Static resources are excellent candidates for caching, so choose the backend caching option in the endpoint definition.

Your configuration file should contain an object like this:

{
"endpoint": "/static/{param1}/{param2}",
"querystring_params": [
"*"
],
"output_encoding": "no-op",
"backend": [
{
"url_pattern": "/static/{param1}/{param2}",
"encoding": "no-op",
"host": [
"https://my.compass.server.com:8190"
],
"extra_config": {
"github.com/devopsfaith/krakend-httpcache": {}
}
}
]
}

6.2.2 APIs

HCL Compass’s REST APIs are found under the /ccmweb/rest path on the URL. HCL Compass’s swagger API documentation can be accessed by pointing your browser at the /swagger-ui.html path on your HCL Compass server. You can navigate here from the API documentation link under the help icon at the top of any HCL Compass screen too.

Krakend lets you add APIs one at a time, or in a group of common APIs. The authenticate API is a good example of an API that can be added specifically. To add it, create an endpoint and point it at /ccmweb/rest/authenticate on your HCL Compass backend. Note that this API defines a POST operation, and its output_encoding and encoding values are set to json to instruct krakend to act like an API gateway instead of a simple proxty You can optionally check the rate limiting box to enable throttling. Here’s what the authenticate API might look like in the krakend configuration file.

{
"endpoint": "/ccmweb/rest/authenticate",
"method": "POST",
"output_encoding": "json",
"backend": [
{
"url_pattern": "/ccmweb/rest/authenticate",
"encoding": "json",
"method": "POST",
"host": [
"https://my.compass.server.com:8190"
]
}
]
}

Other APIs may be grouped together. Take for example, the various record APIs that respond to the HTTP GET method.

{
"endpoint": "/ccmweb/rest/repos/{param1}/databases/{param2}/records/{param3}",
"method": "GET",
"output_encoding": "json",
"backend": [
{
"url_pattern": "/ccmweb/rest/repos/{param1}/databases/{param2}/records/{param3}",
"encoding": "json",
"method": "GET",
"host": [
"https://my.compass.server.com:8190"
]
}
],
"headers_to_pass": [
"Authorization",
"Accept",
"Content-type"
]
}

Notice that the headers_to_pass object specifies the Authorization header (in addition to the basic Accept and Content-type headers). This is required to pass the logged in user’s JWT token between the client and the HCL Compass server.

Checking the rate limiting box to enable throttling will add something like this to the endpoint’s configuration.

{
"endpoint": "/ccmweb/rest/repos/{param1}/databases/{param2}/records/{param3}",
"method": "GET",
"extra_config": {
"github.com/devopsfaith/krakend-ratelimit/juju/router": {
"maxRate": 1,
"clientMaxRate": 1,
"strategy": "ip"
}
},
"output_encoding": "json",
"backend": [
{
"url_pattern": "/ccmweb/rest/repos/{param1}/databases/{param2}/records/{param3}",
"encoding": "json",
"method": "GET",
"host": [
"https:// my.compass.server.com:8190"
]
}
],
"headers_to_pass": [
"Authorization",
"Accept",
"Content-type"
]
}

7. Summary

HCL Compass is designed to support caching of static resources (JavaScript, style sheets, images), but not dynamic resources (APIs). Throttling can be applied to all types of resource to limit load on the server.