WebTSM Services API

Introduction

The single most important configuration file is the "HAKOM.Config" XML-file found in the installation directory. There is a dedicated section under <products> that is exclusively for settings related to the WebTSM Services.

Specific settings for WebTSMServices are located under following base path in the XML structure of HAKOM.config: //HAKOMConfiguration/products/WebTSMServices

The element <WebTSMServices> may have the following attributes:

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 the path //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 the path: //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 the path //HAKOMConfiguration/products/WebTSMServices/Hosting/Ssl/Certificate/Path insert the full path to the pfx file you would like to use.

Under the path //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 the path: //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.

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

Responses

Settings pertaining to WebTSM Service responses are located in this section of the HAKOM.Config:

<HAKOMConfiguration>
	<products>
		<WebTSMServices>
			<Response>
				<!-- Settings -->
			</Response>
		</WebTSMServices>
	</products>
</HAKOMConfiguration>

Application Insights

Azure Application Insights offer application performance monitoring functionality and can be used to monitor and analyze the performance and other logging information of a service. More information can be found here:  https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview

In order to connect a service to Application Insights the "Connection String" provided by Azure must be configured in the HAKOM.Config:

<HAKOMConfiguration>
	<products>
		<WebTSMServices>
			<ApplicationInsights>
				<ConnectionString></ConnectionString>
			</ApplicationInsights>
		</WebTSMServices>
	</products>
</HAKOMConfiguration>