Formatting

Introduction

The HAKOM WebTSM service supports JSON only 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 body's media type - which should also be "application/json"

CODE

Content-Type: application/json

If there is no way to set the header (for example, when calling request from the 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 browser. In that case, it can be beneficial to format the json response in order to make the data more easily readable by adding the "indented" mediatype-parameter:

CODE

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

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

Available Media Type Parameters

indented

This boolean parameter specifies whether additional whitespace 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 whitespace is 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

The default.

Transmits JSON without superfluous whitespace

Example:

JS

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

true

Transmits JSON with additional whitespace

Example:

JS

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

format

This parameter is available whenever time series data is returned. It specifies wether time series data should include a single time stamp only for each point of data, or wether each point of data should inlcude both the start and the end of its period included.

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

The default (starting with version 3.8.2)

Example:

JS

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

Timespan

The default prior to version 3.8.2

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 describes how dates/timestamps are transmitted in JSON. It controls the how these are formatted in responses as well as how the content of POST/PUT requests and query parameters are interpreted.

It can be used wherever dates/timestamps 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

The default (and the only format available prior to version 3.8.6)

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/timestamps 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/timestamps 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
    }
  ]
}