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.

Available backends

Currently available:

API functions

Currently available functionality:

Search channel

Method: GET

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

Query parameters:

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

Method: GET

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

Query parameters:

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

CURL example:

curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/events?channelBackend=sf-databuffer&channelName=SLAAR-LSCP4-LAS6891:CH7:1&begDate=2021-06-11T07:00:00.000Z&endDate=2021-06-11T07:00:01.000Z'

Timestamp format

Javascript can not represent the full 64-bit integer and the databuffer nanosecond timestamps would lose precision. Therefore, timestamps are represented in the response by ts0 which gives an absolute anchor in time in units of seconds, and the array tsoff with the offset of each event in microseconds.

Timeout

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

Example response:

{
  "finalisedRange": true,
  "ts0": 1623394800,
  "tsoff": [
    68461150,
    169461160,
    269461170,
    369461180,
    479461191,
    579461201,
    ...
  ],
  "values": [
    [378, 325, 321, 381, ... waveform of 1st event ],
    [334, 355, 360, 345, ... waveform of 2nd event ],
    ...
  ]
}

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.

Query binned data

Method: GET

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

Query parameters:

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:

{
  "continueAt": "2021-05-25T16:00:00.000Z",
  "missingBins": 2,
  "avgs": [
    340.87640380859375,
    340.7442321777344,
    340.58685302734375,
    341.04608154296875
  ],
  "counts": [
    143076,
    143077,
    143076,
    143076
  ],
  "maxs": [
    452,
    452,
    459,
    458
  ],
  "mins": [
    231,
    240,
    239,
    239
  ],
  "tsBinEdges": [
    "2021-05-25T00:00:00.000Z",
    "2021-05-25T04:00:00.000Z",
    "2021-05-25T08:00:00.000Z",
    "2021-05-25T12:00:00.000Z",
    "2021-05-25T16:00:00.000Z"
  ]
}

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.