Databuffer API 4 Documentation

Documented here are the endpoints for databuffer API 4. The endpoints of the "original" unversioned API is documented at this location.

Timestamp format

The result encodes timestamps in the form:

{
  "tsAnchor": 1623909860,                    // Time-anchor of this result in UNIX epoch seconds.
  "tsOffMs": [573, 15671, 37932, ...],       // Millisecond-offset to tsAnchor for each event/bin-edge.
  "tsOffNs": [422901, 422902, 422903, ...],  // Nanosecond-offset to tsAnchor in addition to tsOffMs for each event/bin-edge.
}

which results in these nanosecond-timestamps:

1623909860573422901
1623909875671422902
1623909897932422903

Formally: tsAbsolute = tsAnchor * 10⁹ + tsOffMs * 10⁶ + tsOffNs

Two reasons lead to this choice of timestamp format:

• Javascript can not represent the full nanosecond-resolution timestamps in a single numeric variable.
• The lowest 6 digits of the nanosecond timestamp are anyway abused by the timing system to emit a pulse-id.

API functions

Currently available functionality:

• List available backends
• Search channel
• Query binned data
• Query unbinned event data

List available backends

Method: GET

URL: https://data-api.psi.ch/api/4/backends

Request header: "Accept" must be "application/json"

CURL example:

curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/backends'

Example response

{
  "backends": [
    "sf-databuffer",
    "hipa-archive",
    "gls-archive",
    "proscan-archive"
  ]
}

Search channel

Method: GET

URL: https://data-api.psi.ch/api/4/search/channel

Query parameters:

• nameRegex (e.g. "LSCP.*6")
• sourceRegex (e.g. "178:9999")
• descriptionRegex (e.g. "celsius")

Request header: "Accept" must be "application/json"

CURL example:

curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/search/channel?sourceRegex=CV.E.+37&nameRegex=120.+y2$'

Example response:

{
  "channels": [
    {
      "name": "S10MA01-DBPM120:Y2",
      "backend": "sf-databuffer",
      "source": "tcp://S20-CVME-DBPM2371:9000",
      "type": "Float32",
      "shape": [],
      "unit": "",
      "description": ""
    },
    {
      "name": "S20SY02-DBPM120:Y2",
      "backend": "sf-databuffer",
      "source": "tcp://S20-CVME-DBPM2371:9000",
      "type": "Float32",
      "shape": [],
      "unit": "",
      "description": ""
    }
  ]
}

The search constraints are AND'd.

Query event data

Returns the full event values in a given time range.

Method: GET

URL: https://data-api.psi.ch/api/4/events

Query parameters:

• channelBackend (e.g. "sf-databuffer")
• channelName (e.g. "S10CB02-RBOC-DCP10:FOR-AMPLT-AVG")
• begDate (e.g. "2021-05-26T07:10:00.000Z")
• endDate (e.g. "2021-05-26T07:16:00.000Z")

Request header: "Accept" must be "application/json"

Timeout

If the requested range takes too long to retrieve, then the flags timedOut: true will be set.

CURL example:

curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/events?channelBackend=sf-databuffer
  &channelName=S10CB02-RBOC-DCP10:FOR-AMPLT-AVG&begDate=2021-05-26T07:10:00.000Z&endDate=2021-05-26T07:16:00.000Z'

Example response:

{
  "finalisedRange": true,
  "tsAnchor": 1623763172,
  "tsMs": [
    5,
    15,
    25,
    35
  ],
  "tsNs": [
    299319,
    299320,
    299321,
    299322
  ],
  "values": [
    0.6080216765403748,
    0.6080366969108582,
    0.6080275177955627,
    0.6080636382102966
  ]
}

Finalised range

If the server can determine that no more data will be added to the requested time range then it will add the flag finalisedRange: true to the response.

Query binned data

Method: GET

URL: https://data-api.psi.ch/api/4/binned

Query parameters:

• channelBackend (e.g. "sf-databuffer")
• channelName (e.g. "SLAAR-LSCP4-LAS6891:CH7:1")
• begDate (e.g. "2021-05-26T07:10:00.000Z")
• endDate (e.g. "2021-05-26T07:16:00.000Z")
• binCount (number of requested bins in time-dimension, e.g. "6")
• binningScheme (optional)
• if not specified: waveform gets first binned to a scalar.
• "binningScheme=binnedX&binnedXcount=13": waveform gets first binned to 13 bins in X-dimension (waveform-dimension).
• "binningScheme=binnedX&binnedXcount=0": waveform is not binned in X-dimension but kept at full length.

Request header: "Accept" must be "application/json"

CURL example:

curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/binned?channelBackend=sf-databuffer
  &channelName=SLAAR-LSCP4-LAS6891:CH7:1&begDate=2021-05-25T00:00:00.000Z&endDate=2021-05-26T00:00:00.000Z&binCount=3'

Partial result

If the requested range takes longer time to retrieve, then a partial result with at least one bin is returned. The partial result will contain the necessary information to send another request with a range that starts with the first not-yet-retrieved bin. This information is provided by the continueAt and missingBins fields. This enables the user agent to start the presentation to the user while updating the user interface as new bins are received.

Example response (without usage of binningScheme):

{
  "avgs": [
    16204.087890625,
    16204.3798828125,
    16203.9296875,
    16204.232421875,
    16202.974609375,
    16203.208984375,
    16203.4345703125
  ],
  "counts": [
    1000,
    999,
    1000,
    999,
    1000,
    999,
    1000
  ],
  "finalisedRange": true,
  "maxs": [
    48096,
    48100,
    48094,
    48096,
    48096,
    48095,
    48096
  ],
  "mins": [
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ],
  "tsAnchor": 1623769850,
  "tsMs": [
    0,
    10000,
    20000,
    30000,
    40000,
    50000,
    60000,
    70000
  ],
  "tsNs": [
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ]
}

Example response (waveform channel and usage of binningScheme):

{
  "tsAnchor": 1623769950,
  "tsMs": [
    0,
    10000,
    20000,
    30000,
    40000,
    50000,
    60000,
    70000
  ],
  "tsNs": [
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0
  ],
  "finalisedRange": true,
  "counts": [
    1000,
    1000,
    ...
  ],
  "avgs": [
    [
      0.013631398789584637,
      34936.76953125,
      45045.5078125,
      31676.30859375,
      880.7999877929688,
      576.4010620117188,
      295.1236877441406
    ],
    [
      0.01851877197623253,
      34935.734375,
      45044.2734375,
      31675.359375,
      880.7310791015625,
      576.3038330078125,
      295.06134033203125
    ],
    ...
  ],
  "maxs": [
    [
      111,
      48093,
      45804,
      47122,
      1446,
      783,
      431
    ],
    [
      120,
      48092,
      45803,
      47124,
      1452,
      782,
      431
    ],
    ...
  ],
  "mins": [
    [
      0,
      0,
      44329,
      267,
      519,
      394,
      0
    ],
    [
      0,
      0,
      44327,
      265,
      514,
      395,
      0
    ],
    ...
  ]
}

Complete result

If the result does not contain a continueAt key then the result is complete.

Finalised range

If the server can determine that no more data will be added to the requested time range then it will add the flag finalisedRange: true to the response.

Feedback and comments very much appreciated!

dominik.werder@psi.ch

or please assign me a JIRA ticket.