Documented here is the databuffer http api 4. The "original" unversioned api is documented at this location.
API version 1: https://data-api.psi.ch/api/1/documentation/
In order to keep the api surface as small as possible in comparison to api 0, we add functionality on demand, so please feel free to create some Jira ticket!
The result encodes timestamps in the form:
{
"tsAnchor": 1623909860, // Time-anchor of this result in UNIX epoch seconds.
"tsOffMs": [173, 472, 857, ...], // 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 * 109 + tsOffMs * 106 + tsOffNs
Two reasons lead to this choice of timestamp format:
Currently available functionality:
Method: GET
URL: https://data-api.psi.ch/api/4/backends
Request header: "Accept" must be "application/json"
curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/backends'
{
"backends": [
"sf-databuffer",
"hipa-archive",
"gls-archive",
"proscan-archive"
]
}
Method: GET
URL: https://data-api.psi.ch/api/4/search/channel
Query parameters: (all optional)
Request header: "Accept" must be "application/json"
Full channel list is long, so it's encouraged to provide a search string of some minimal length.
curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/search/channel?sourceRegex=CV.E.+37&nameRegex=120.+y2$'
Keys always present: name, backend.
Other keys are optional, it depends on the data found on disk: sometimes there is an empty string on disk, sometimes that key is missing.
{
"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": ""
},
{
"isApi0": true,
"name": "EXAMPLE-CHANNEL-FROM-API-0-BACKEND",
"backend": "twlha-databuffer",
"source": "tcp://.....",
"type": "int32",
"shape": [],
"unit": "",
"description": ""
}
]
}
The search constraints are AND'd.
Returns the full event values in a given time range.
Method: GET
URL: https://data-api.psi.ch/api/4/events
Query parameters:
Request header: "Accept" must be "application/json"
If the requested range takes too long to retrieve, then the flags timedOut: true will be set.
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
]
}
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.
Method: GET
URL: https://data-api.psi.ch/api/4/binned
Query parameters:
Request header: "Accept" must be "application/json"
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'
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.
{
"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
]
}
{
"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
],
...
]
}
If the result does not contain a continueAt key then the result is complete.
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.
dominik.werder@psi.ch
or please assign me a JIRA ticket.