daqbuf/daqbuffer
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move /api/1/ related proxy functionality

Browse Source
This commit is contained in:
Dominik Werder
2021-06-17 18:32:05 +02:00
parent 7077d6b09a
commit 0d73251db8
16 changed files with 848 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

309
httpret/static/documentation/api4.html
View File

@@ -23,12 +23,31 @@ Currently available:
</ul>
<h2>Timestamp format</h2>
<p>The result encodes timestamps in the form:</p>
<pre>{
"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.
}</pre>
<p>which results in these nanosecond-timestamps:</p>
<pre>1623909860573422901
1623909875671422902
1623909897932422903</pre>
<p>Formally: tsAbsolute = tsAnchor * 10<sup>9</sup> + tsOffMs * 10<sup>6</sup> + tsOffNs</p>
<p>Two reasons lead to this choice of timestamp format:</p>
<ul>
<li>Javascript can not represent the full nanosecond-resolution timestamps in a single numeric variable.</li>
<li>The lowest 6 digits of the nanosecond timestamp are anyway abused by the timing system to emit a pulse-id.</li>
</ul>
<h2>API functions</h2>
<p>Currently available functionality:</p>
<ul>
<li><a href="#search-channel">Search channel</a></li>
<li><a href="#query-binned">Query binned data</a></li>
<li><a href="#query-events">Query event data</a></li>
<li><a href="#query-events">Query unbinned event data</a></li>
</ul>
@@ -82,56 +101,56 @@ curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/search/channel
<a id="query-events"></a>
<h2>Query event data</h2>
<p>Returns the full event values in a given time range.</p>
<p><strong>Method:</strong> GET</p>
<p><strong>URL:</strong> https://data-api.psi.ch/api/4/events</p>
<p><strong>Query parameters:</strong></p>
<ul>
<li>channelBackend (e.g. "sf-databuffer")</li>
<li>channelName (e.g. "SLAAR-LSCP4-LAS6891:CH7:1")</li>
<li>channelName (e.g. "S10CB02-RBOC-DCP10:FOR-AMPLT-AVG")</li>
<li>begDate (e.g. "2021-05-26T07:10:00.000Z")</li>
<li>endDate (e.g. "2021-05-26T07:16:00.000Z")</li>
</ul>
<p><strong>Request header:</strong> "Accept" must be "application/json"</p>
<h4>Timeout</h4>
<p>If the requested range takes too long to retrieve, then the flags <strong>timedOut: true</strong> will be set.</p>
<h4>CURL example:</h4>
<pre>
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'
&channelName=S10CB02-RBOC-DCP10:FOR-AMPLT-AVG&begDate=2021-05-26T07:10:00.000Z&endDate=2021-05-26T07:16:00.000Z'
</pre>
<h4>Timestamp format</h4>
<p>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 <strong>ts0</strong> which gives an absolute anchor
in time in units of seconds, and the array <strong>tsoff</strong> with the offset of each event in nanoseconds.</p>
<h4>Timeout</h4>
<p>If the requested range takes too long to retrieve, then the flags <strong>timedOut: true</strong> will be set.</p>
<p>Example response:</p>
<pre>
{
"finalisedRange": true,
"ts0": 1623394800,
"tsoff": [
68461150,
169461160,
269461170,
369461180,
479461191,
579461201,
...
"tsAnchor": 1623763172,
"tsMs": [
5,
15,
25,
35
],
"tsNs": [
299319,
299320,
299321,
299322
],
"values": [
[378, 325, 321, 381, ... waveform of 1st event ],
[334, 355, 360, 345, ... waveform of 2nd event ],
...
0.6080216765403748,
0.6080366969108582,
0.6080275177955627,
0.6080636382102966
]
}
</pre>
<h4>Finalised range</h4>
<p>If the server can determine that no more data will be added to the requested time range
then it will add the flag <strong>finalisedRange: true</strong> to the response.</p>
then it will add the flag <strong>finalisedRange: true</strong> to the response.</p>
@@ -142,11 +161,17 @@ in time in units of seconds, and the array <strong>tsoff</strong> with the offse
<p><strong>URL:</strong> https://data-api.psi.ch/api/4/binned</p>
<p><strong>Query parameters:</strong></p>
<ul>
<li>channelBackend (e.g. "sf-databuffer")</li>
<li>channelName (e.g. "SLAAR-LSCP4-LAS6891:CH7:1")</li>
<li>begDate (e.g. "2021-05-26T07:10:00.000Z")</li>
<li>endDate (e.g. "2021-05-26T07:16:00.000Z")</li>
<li>binCount (e.g. "6")</li>
<li>channelBackend (e.g. "sf-databuffer")</li>
<li>channelName (e.g. "SLAAR-LSCP4-LAS6891:CH7:1")</li>
<li>begDate (e.g. "2021-05-26T07:10:00.000Z")</li>
<li>endDate (e.g. "2021-05-26T07:16:00.000Z")</li>
<li>binCount (number of requested bins in time-dimension, e.g. "6")</li>
<li>binningScheme (optional)</li>
<ul>
<li>if not specified: waveform gets first binned to a scalar.</li>
<li>"binningScheme=binnedX&binnedXcount=13": waveform gets first binned to 13 bins in X-dimension (waveform-dimension).</li>
<li>"binningScheme=binnedX&binnedXcount=0": waveform is not binned in X-dimension but kept at full length.</li>
</ul>
</ul>
<p><strong>Request header:</strong> "Accept" must be "application/json"</p>
@@ -157,89 +182,167 @@ curl -H 'Accept: application/json' 'https://data-api.psi.ch/api/4/binned?channel
</pre>
<h4>Partial result</h4>
<p>If the requested range takes longer time to retrieve, then a partial result with at least one bin is returned.</p>
<p>The partial result will contain the necessary information to send another request with a range that
starts with the first not-yet-retrieved bin.</p>
<p>This information is provided by the <strong>continueAt</strong> and <strong>missingBins</strong> fields.</p>
<p>This enables the user agent to start the presentation to the user while updating the user interface
<p>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 <strong>continueAt</strong> and <strong>missingBins</strong> fields.
This enables the user agent to start the presentation to the user while updating the user interface
as new bins are received.</p>
<p>Example response:</p>
<pre>
{
"ts0": 1623304800,
"missingBins": 1,
"continueAt": 86400000000000,
"tsoff": [
0,
7200000000000,
14400000000000,
21600000000000,
28800000000000,
36000000000000,
43200000000000,
50400000000000,
57600000000000,
64800000000000,
72000000000000,
79200000000000,
86400000000000
],
<h4>Example response (without usage of binningScheme):</h4>
<pre>{
"avgs": [
341.3874206542969,
341.5171203613281,
341.70989990234375,
341.2113952636719,
341.84088134765625,
342.1435546875,
341.16558837890625,
342.2756652832031,
342.9447326660156,
343.0351867675781,
342.6963195800781,
342.054931640625
16204.087890625,
16204.3798828125,
16203.9296875,
16204.232421875,
16202.974609375,
16203.208984375,
16203.4345703125
],
"counts": [
71539,
71537,
71538,
71539,
71538,
71537,
71538,
71539,
71539,
71539,
71538,
71299
1000,
999,
1000,
999,
1000,
999,
1000
],
"finalisedRange": true,
"maxs": [
450,
450,
462,
458,
454,
450,
452,
451,
450,
453,
464,
448
48096,
48100,
48094,
48096,
48096,
48095,
48096
],
"mins": [
224,
239,
242,
235,
243,
239,
239,
241,
243,
229,
244,
225
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
]
}
</pre>
<h4>Example response (waveform channel and usage of binningScheme):</h4>
<pre>{
"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
],
...
]
}
</pre>