Formatting

Introduction

The HAKOM WebTSM Services only support JSON for data exchange with a client.

All requests should have an "Accept" header specifying that the client accepts the media type "application/json"

CODE

Accept: application/json

POST/PUT requests with a payload should also include a "Content-Type" header, specifying the media type of the request body - which should also be "application/json"

CODE

Content-Type: application/json

If there is no way to set the header (for example, when calling requests from a web browser), the accepted format can also be controlled by using a query parameter

CODE

GET /repositories/{repository}/timeseries?mediaType=application/json

This is mostly needed for testing purposes from a web browser. In these cases, it can be beneficial to format the JSON response in order to make the data more easily readable by adding the "indented" media type parameter:

CODE

GET /repositories/{repository}/timeseries?mediaType=application/json;indented=true

This indentation should be avoided when using the service programmatically though, since it does not affect the actual content and only increases the amount of data that has to be transferred.

Serialisation

Double.NaN and Double.Infinity values are replaced with 0 in the JSON response as it is not possible to serialise these two data types via System.JSON due to the JSON specification. For more information please visit: datatracker.ietf.org

Example: A division by 0 returns 0 instead of Double.NaN in the JSON response.

This behaviour should make it easier to find errors in the calculation of formulas.

Available Media Type Parameters

indented

This boolean parameter specifies whether additional whitespaces should be added to the response in order to make the result more easily readable. Adding this parameter to the Content-Type header of a POST or PUT request has no effect as whitespaces are ignored during parsing of the request content. Because of the additional data that has to be transferred, it is advisable not to use this parameter except when manually testing/trying out requests.

Valid values are:

false

This is the default setting and will transmit JSON without additional whitespaces.

Example:

JS

{"Name":"HAKOM WebTSM Services","Description":"Time Series Management Webservices","Version":"3.9.2.0+26666"}

true

Transmits JSON with additional whitespaces.

Example:

JS

{
  "Name": "HAKOM WebTSM Services",
  "Description": "Time Series Management Webservices",
  "Version": "3.9.2.0+26666"
}

format

This parameter is available whenever time series data is returned. It specifies whether time series data should include a time stamp or "from" and "to" dates for each data point.

This parameter may also be used in the Content-Type header when sending time series data to the service.

Valid values are (all examples are shown using the "indented" parameter set to "true" for readability):

Timestamp

By default time series data will be provided with time stamps.

Example:

JS

{
  "Interval": {
    "Value": 1,
    "Multiplier": 3600
  },
  "Unit": "cm/m2",
  "Data": [
    {
      "From": "2010-01-01T00:00:00Z",
      "Value": 123.4,
      "Flag": 9
    }
  ]
}

Timespan

Example:

JS

[
  {
    "From": "2017-05-01T00:00:00Z",
    "To": "2017-05-01T01:00:00Z",
    "Value": 1,
    "Flag": 9
  },
  {
    "From": "2017-05-01T01:00:00Z",
    "To": "2017-05-01T02:00:00Z",
    "Value": 2,
    "Flag": 9
  }
]

dateformat

This parameter specifies how dates are transmitted in JSON. It controls how dates are formatted in responses as well as how the content of POST/PUT requests and query parameters are interpreted.

The "dateformat" parameter can be used wherever dates are contained in either the response or the request body.

Valid values are (all examples are shown using the "indented" parameter set to "true" for readability):

ISO8601

By default dates will be formatted according to this standard.

Example:

JS

{
  "Interval": {
    "Value": 1,
    "Multiplier": 3600
  },
  "Unit": "cm/m2",
  "Data": [
    {
      "From": "2010-01-01T00:00:00Z",
      "Value": 123.4,
      "Flag": 9
    }
  ]
}

Epoch

Transmits dates as an integer representing the number of seconds that have passed since the Unix Epoch (January 1st 1970, 00:00 UTC)

Example:

JS

{
  "Interval": {
    "Value": 1,
    "Multiplier": 3600
  },
  "Unit": "cm/m2",
  "Data": [
    {
      "From": 1651351234,
      "Value": 123.4,
      "Flag": 9
    }
  ]
}

EpochMilliseconds

Transmits dates as an integer representing the number of milliseconds that have passed since the Unix Epoch (January 1st 1970, 00:00 UTC)

Example:

JS

{
  "Interval": {
    "Value": 1,
    "Multiplier": 3600
  },
  "Unit": "cm/m2",
  "Data": [
    {
      "From": 1651351234654,
      "Value": 123.4,
      "Flag": 9
    }
  ]
}