WebTSM Services

Introduction

The single most important configuration file is the "HAKOM.Config" XML-file found in the installation directory.

As of version 3.7.0, there is a separate section under <products> that is exclusively for settings related to the WebTSM Services.

The element <WebTSMServices> may have the following attributes:

Logging Configuration Examples

The following causes only errors to be logged (rule of thumb: any HTTP Status code >= 400):

<WebTSMServices LogLevel="Error">
</WebTSMServices>

The following causes nothing to be logged:

<HAKOMConfiguration>
    <products>
		<WebTSMServices LogLevel="None">
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

The following causes even successful requests to be logged as well as any other informative messages, and also writes these logs to a file called "requests.log" (instead of the default file "HAKOM.Framework.Services.log") within the installation directory of the service:

<HAKOMConfiguration>
    <products>		
		<WebTSMServices LogLevel="Information"
 				LogFile="requests.log">
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

The following causes only errors to be logged. The log file will have the default name "HAKOM.Framework.Services.log". It will have a maximum size of 1GB. A new file is generated when the current file has reached its maximum size (1GB in this case) or a new day has started. From the sixth file onwards, each newly created file will overwrite the oldest:

<HAKOMConfiguration>
    <products>
		<WebTSMServices LogLevel="Error"
 				FileSizeLimitBytes="1073741824"
				RetainedFileCountLimit="5"
				RollingInterval="Day"
				RollOnFileSizeLimit="true">
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

The following causes errors to be logged as JSON objects inside the log file instead of the default text-format

<HAKOMConfiguration>
    <products>
		<WebTSMServices LogLevel="Error"
 				LogFormat="JSON">
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

Proxy Header Configuration Examples

This is required for proper generation of links in specification files under /docs if you host the services behind a reverse proxy (IIS, nginx, etc)

Please note that this does not affect "Location" header values in 3xx redirects. Most reverse proxies already have well established methods of rewriting these in outgoing responses.

<HAKOMConfiguration>
    <products>
		<WebTSMServices ProxyUrlHeader="X-Original-URL">
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

This looks for a header "X-Original-URL" in the request and uses this to generate links. This should be a fully qualified URI including Protocol, Hostname, non-standard ports, etc. that the proxy sets.

For example:

X-Original-URL: https://loadbalancer.mycompany.com:8080/webtsm/docs/specification.json

You may also configure the proxy to pass individual parts of this url in individual headers.

For Example:

<HAKOMConfiguration>
    <products>
		<WebTSMServices 
			ProxyProtocolHeader="X-Original-Scheme"
			ProxyHostHeader="X-Original-Host"
			ProxyPathHeader="X-Request-Path"
			>
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

Then configure your proxy to add these headers accordingly:

X-Original-Scheme: https
X-Original-Host: loadbalancer.mycompany.com:8080
X-Request-Path: /webtsm/docs/specification.json

Hosting Options

Url Configuration

The following setting causes the service to be accessible under http://[ip-or-hostname-of-the-machine]:8080/api: 

<HAKOMConfiguration>
    <products>
		<WebTSMServices>
			<Hosting>
				<Url>http://+:8080/api</Url>
			</Hosting>
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

The following setting causes the service to be accessible under https://customdomain.com:1234/tsm/api: 

Note that this requires further configuration of the SSL certificate to be used (see below)

<HAKOMConfiguration>
    <products>
		<WebTSMServices>
			<Hosting>
				<Url>https://customdomain.com:1234/tsm/api</Url>
			</Hosting>
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

The following setting causes the service to be accessible under  https://[ip-or-hostname-of-the-machine]/api: 

Note that this requires further configuration of the SSL certificate to be used (see below)

<HAKOMConfiguration>
    <products>
		<WebTSMServices>
			<Hosting>
				<Url>https://+/api</Url>
			</Hosting>
		</WebTSMServices>
    </products>
</HAKOMConfiguration>

Limits

Under //HAKOMConfiguration/products/WebTSMServices/Hosting/Limits several settings can be changed to affect performance and behavior of the service.

<HAKOMConfiguration>
    <products>   
        <WebTSMServices>
            <Hosting>
                <Limits>
					<Serialization>500000</Serialization>
                    <KeepAliveTimeout>00:02:00</KeepAliveTimeout>
                    <MaxConcurrentConnections></MaxConcurrentConnections>
                    <MaxRequestLineSize>8192</MaxRequestLineSize>
                    <MaxRequestHeaderCount>100</MaxRequestHeaderCount>
                    <MaxRequestHeadersTotalSize>32786</MaxRequestHeadersTotalSize>
                    <RequestHeadersTimeout>00:00:30</RequestHeadersTimeout>
                    <MaxRequestBufferSize>1048576</MaxRequestBufferSize>
                    <MaxRequestBodySize>30000000</MaxRequestBodySize>
                    <MinRequestBodyDataRate>
                        <BytesPerSecond>240</BytesPerSecond>
                        <GracePeriod>00:00:05</GracePeriod>
                    </MinRequestBodyDataRate>
                    <MaxResponseBufferSize>65536</MaxResponseBufferSize>
                    <MinResponseDataRate>
                        <BytesPerSecond>240</BytesPerSecond>
                        <GracePeriod>00:00:05</GracePeriod>
                    </MinResponseDataRate>
                </Limits>
            </Hosting>
        </WebTSMServices>
    </products>
</HAKOMConfiguration>

All of these settings are optional. Default values apply.

8192 = 8 KB

If a tag is not contained in the HAKOM.Config, its default value is used. The tags cannot be empty (except for <MaxConcurrentConnections>, which defaults to unlimited when empty).

SSL Configuration

When specifying a Url that starts with "https", a certificate has to be configured that should be used for encryption of communication with clients.

This configuration is found under //HAKOMConfiguration/products/WebTSMServices/Hosting/Ssl/Certificate

<HAKOMConfiguration>
  <products>
    <WebTSMServices>
      <Hosting>
        <Ssl>
          <Certificate>
            <Thumbprint>...</Thumbprint>
			<!-- or: ->
            <Path>...</Path>
            <Password>...</Password>
          </Certificate>
        </Ssl>
      </Hosting>
    </WebTSMServices>
  </products>
</HAKOMConfiguration>

There are two ways of configuring the certificate

Using a Certificate From the Local Certificate Store

Insert the hash/thumbprint of the locally installed certificate under //HAKOMConfiguration/products/WebTSMServices/Hosting/Ssl/Certificate/Thumbprint

Using a Certificate From the Local File System

Under //HAKOMConfiguration/products/WebTSMServices/Hosting/Ssl/Certificate/Path insert the full path to the pfx file you would like to use.

Under //HAKOMConfiguration/products/WebTSMServices/Hosting/Ssl/Certificate/Password insert the password used to retrieve the private key from the certificate.

Cross Origin Resource Sharing (CORS)

Some client applications may require specific values in the Accept-Origin Header. By default a wildcard value ( * ) is sent, but this may interfere with authentication when accessing the service from a web browser.

In order to allow specific hosts (origins) to access the service without issues, consider adding the origin to the setting found under

//HAKOMConfiguration/products/WebTSMServices/Cors

<HAKOMConfiguration>
  <products>
    <WebTSMServices>
	  <Cors>
	    <Origins>
	      <Origin>http://localhost:8081</Origin>
	      <Origin>https://www.some-web-app</Origin>
	    </Origins>
	  </Cors>
    </WebTSMServices>
  </products>
</HAKOMConfiguration>

Request based default api versions

Some client applications might have a hard time globally setting media type headers to appropriate values and/or may wish to keep a range of request endpoints at one version while upgrading to another version for all other requests,

To accomodate this, you may configure the default api versions for specific requests as follows:

<HAKOMConfiguration>
	<products>
		<WebTSMServices>
				<Versioning>
    				<Version Methods="GET,PUT,POST" Path="\/repositories\/.*?\/timeseries.*">3.8.0</Version>
    				<Version Methods="GET" Path="\/extensions.*">Latest</Version>
				</Versioning>
		</WebTSMServices>
	</products>
</HAKOMConfiguration>

Wherein

• Method is a comma separated list of standard HTTP Methods. Only requests with the specified method will have this default value applied. Use "*" as a shortcut to match all supported methods (POST,GET,PUT,DELETE)
• Path is a Regular Expression to match the path of the request. Syntax is based on .NET Regex syntax. Backreferences via named groups, etc. are not supported.
• Version can be either the string "Latest" or the version number (major.minor.revision) just as you would use in the media type.

• Values for api-version within the Accept or Content-Type header will always be honored first, overriding any configuration here.
• Values for api-version in a "mediaType" query parameter will always be honored first
• Path and Method will be matched against the list from top to bottom. First match wins.
• Requests that do not match any will - as before - be treated as requests for the latest version.

Events

In order to enable Events globally (and thus, enable Webhooks for consumers of the service), make sure you've adjusted the configuration file accordingly.

Example

<HAKOMConfiguration>
    <products>
        <WebTSMServices>
            <Events>
                <Enabled>true</Enabled><!-- Globally enables(true)/disables(false) events Default: false-->
                <Limits>
                    <MaxRequestContent>524288</MaxRequestContent><!-- Maximum size of request body that can be sent to the event-subscriber (in Byte). Default: 524288 Byte = 512 KB-->
                </Limits>
            </Events>
        </WebTSMServices>
    </products>
</HAKOMConfiguration>

Millisecond Interval Support

In order to enable the support for milliseconds as intervals, set the "InternalTimeUnit" setting accordingly:

<HAKOMConfiguration>
  <products>
    <HAKOMFramework>
      <settings>
        <InternalTimeUnit>2</InternalTimeUnit>
      </settings>
    </HAKOMFramework>
  </products>
</HAKOMConfiguration>

Possible values are:

• 0:  (default), Seconds, Starting 1972-01-01T00:00:00+01:00
• 1:  Seconds, Starting 1970-01-01T00:00:00Z
• 2:  Milliseconds, Starting 1970-01-01T00:00:00Z

The default value is 0.

Note that this has to be enabled in the underlying database as well (see Configuration)

Logging

The default logging of the HAKOM WebTSM Services can be extended to include information about the database connection as well as any database commands included in a request. The settings can be adjusted in the HAKOM.Config:

<HAKOMConfiguration>
    <products>
        <WebTSMServices>
            <Logging>
                <DbConnections>true<DbConnections> <!--DEFAULT: false -->
                <DbCommands>true<DbCommands> <!--DEFAULT: false -->
            </Logging>
        </WebTSMServices>
    </products>
</HAKOMConfiguration>

Content Encoding

The service is able to accept request content and return responses in one of the following formats:

• Deflate https://en.wikipedia.org/wiki/Deflate
• Gzip https://www.gzip.org/
• Brotli https://github.com/google/brotli

Usually, client software specifies the desired encoding using the

Accept-Encoding

and

Content-Encoding

headers.

If the client does not specify an encoding, the requests are expected to contain unencoded data and responses will be returned without any additional encoding as well.

If a different default encoding is to be used in responses to requests without an Accept-Encoding header, you may specify this in the configuration section ContentNegotiation under DefaultEncoding:

<HAKOMConfiguration>
	<products>
		<WebTSMServices>
			<ContentNegotiation>
				<DefaultEncoding>gzip</DefaultEncoding>
			</ContentNegotiation>
		</WebTSMServices>
	</products>
</HAKOMConfiguration>

Valid values are

• deflate
• gzip
• br