WIP

apidoc/src/backends.md

@@ -5,3 +5,14 @@ The list of available backends can be queried:
 ```bash
 curl "https://data-api.psi.ch/api/4/backend/list"
 ```
+
+Example output:
+```json
+{
+  "backends_available": [
+    {"name": "sf-archiver"},
+    {"name": "sls-archiver"},
+    {"name": "sf-databuffer"}
+  ]
+}
+```

apidoc/src/bins.md

@@ -28,6 +28,62 @@ The server may return more than `binCount` bins, and it will choose a `binWidth`
 supported widths to best possibly match the requested width.
 
 
+Example response, truncated to 4 bins:
+```json
+{
+  "avgs": [
+    0.010802877135574818,
+    0.010565019212663174,
+    0.01061472948640585,
+    0.010656529106199741
+  ],
+  "counts": [
+    3000,
+    2999,
+    3000,
+    3000
+  ],
+  "maxs": [
+    0.017492100596427917,
+    0.016716860234737396,
+    0.01769270747900009,
+    0.01670699194073677
+  ],
+  "mins": [
+    0.005227561108767986,
+    0.0040797283872962,
+    0.004329073242843151,
+    0.004934651777148247
+  ],
+  "ts1Ms": [
+    0,
+    300000,
+    600000,
+    900000
+  ],
+  "ts1Ns": [
+    0,
+    0,
+    0,
+    0
+  ],
+  "ts2Ms": [
+    300000,
+    600000,
+    900000,
+    1200000
+  ],
+  "ts2Ns": [
+    0,
+    0,
+    0,
+    0
+  ],
+  "tsAnchor": 1726394700
+}
+```
+
+
 ## As framed JSON stream
 
 To download larger amounts data as JSON it is recommended to use the `json-framed` content encoding.

apidoc/src/events.md

@@ -9,6 +9,9 @@ curl "https://data-api.psi.ch/api/4/events?backend=sf-databuffer&channelName=S10
 Parameters:
 - `backend`: the backend that the channel exists in, e.g. `sf-databuffer`.
 - `channelName`: the name of the channel.
+- `seriesId`: instead of a channel name, can specify the (unique within backend) series id
+  as returned by channel search.
+  Note that it is an error to provide both `channelName` and `seriesId`.
 - `begDate`: start of the time range, inclusive. In ISO format e.g. `2024-02-15T12:41:00Z`.
 - `endDate`: end of the time range, exclusive.
 - `oneBeforeRange`: if set to `true` the reponse will in addition also contain the most recent event before the given range.

apidoc/src/search.md

@@ -4,8 +4,42 @@ To search for e.g. DBPM channels in `sf-databuffer` that end in `:Q1` the reques
 looks like this:
 
 ```bash
-curl "https://data-api.psi.ch/api/4/search/channel?backend=sf-databuffer&nameRegex=DBPM.*Q1$"
+curl "https://data-api.psi.ch/api/4/search/channel?backend=sf-archiver&nameRegex=S10CB08-KBOC-HP.*PI-OUT"
 ```
 
 Parameters:
 - `icase=true` uses case-insensitive search (default: case-sensitive).
+
+
+Example response:
+```json
+{
+  "channels": [
+    {
+      "backend": "sf-archiver",
+      "name": "S10CB08-KBOC-HPPI1:PI-OUT",
+      "seriesId": 6173407188734815544,
+      "source": "",
+      "type": "f64",
+      "shape": [],
+      "unit": "",
+      "description": ""
+    }
+  ]
+}
+```
+
+The response contains a list of matching channels.
+For each channel, the search returns:
+
+- `backend`
+- `name`
+- `seriesId`: a 63 bit id which identifies the combination of name, type and shape
+  in a unique way within a backend. Therefore, if the type of a channel changes, it will
+  also generate an additional new `seriesId`.
+- `type`: the scalar data type, for example `i16`, `u64`, `f32`, `enum`, `string`, `bool`.
+- `shape`: a `[]` means scalar, a `[512]` indicates a 512 element waveform.
+
+Note that "source", "unit" and "description" are in the return value for historical reasons.
+Unfortunately, the data is often not available, and in general may also change over time.
+Therefore, "source", "unit" and "description" are deprecated and will get removed.