sf_daq/ch.psi.daq.queryrest#1:

- updating docs, rearranging a little

Readme.md

@@ -138,44 +138,12 @@ By default, no data is compressed when transferred from the server to the client
 
 If compression is enabled, we have to tell `curl` that the data is compressed so that it is being decompressed automatically. `curl` decompresses the response when the `--compressed` parameter is set:
 
-#### Example
-
-```bash
-curl --compressed -H "Content-Type: application/json" -X POST -d '{"compression":"gzip","range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query
-```
-
-
 ### `responseFormat`: data is in JSON by default
 
 Responses can be formatted as CSV or JSON using the `responseFormat` field. The returned data is JSON-formatted per default. 
 
 CSV export does not support `index` and `extrema` aggregations.
 
-#### Example
-
-```bash
-curl -H "Content-Type: application/json" -X POST -d '{"responseFormat":"csv","range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"],"fields":["channel","pulseId","iocMillis","iocNanos","globalMillis","globalNanos","shape","eventCount","value"]}' http://data-api.psi.ch/sf/query
-```
-
-#### Response example
-
-The response is in CSV.
-
-```text
-channel;pulseId;iocMillis;iocNanos;globalMillis;globalNanos;shape;eventCount;value
-testChannel1;0;0;0;0;0;[1];1;0
-testChannel1;1;10;0;10;0;[1];1;1
-testChannel1;2;20;0;20;0;[1];1;2
-testChannel1;3;30;0;30;0;[1];1;3
-testChannel1;4;40;0;40;0;[1];1;4
-testChannel2;0;0;0;0;0;[1];1;0
-testChannel2;1;10;0;10;0;[1];1;1
-testChannel2;2;20;0;20;0;[1];1;2
-testChannel2;3;30;0;30;0;[1];1;3
-testChannel2;4;40;0;40;0;[1];1;4
-``` 
-
-
 
 ### Query request endpoint
 
@@ -202,79 +170,6 @@ The following attributes can be specified:
 - **compression**: Defines the compression algorithm to use, default value is **none**, see all values [here](https://git.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/Compression.java))
 - **responseFormat**: Specifies the format the response of the requested data is in, either in JSON or CSV format, default value **json**, see all values [here](https://git.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/ResponseType.java))
 
-### Example
-
-Compressed data but uncompressed by `curl`:
-
-```bash
-curl --compressed -H "Content-Type: application/json" -X POST -d '{"compression":"deflate","range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"]}' http://data-api.psi.ch/sf/query
-```
-
-Raw, uncompressed data (returns non-human-readable data):
-
-```bash
-curl -H "Content-Type: application/json" -X POST -d '{"range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"]}' http://data-api.psi.ch/sf/query
-```
-
-### Response example
-
-The response is in JSON. 
-
-```json
-[
-   {
-      "channel":"channel1",
-      "data":[
-         {
-            "pulseId":0,
-            "iocMillis":0,
-            "iocNanos":0,
-            "globalMillis":0,
-            "globalNanos":0,
-            "value":0
-         },
-         {
-            "pulseId":2,
-            "iocMillis":2,
-            "iocNanos":2,
-            "globalMillis":2,
-            "globalNanos":2,
-            "value":2
-         },
-         {
-            "pulseId":4,
-            "iocMillis":4,
-            "iocNanos":4,
-            "globalMillis":4,
-            "globalNanos":4,
-            "value":4
-         }
-      ]
-   },
-   {
-      "channel":"channel2",
-      "data":[
-         {
-            "pulseId":1,
-            "iocMillis":1,
-            "iocNanos":1,
-            "globalMillis":1,
-            "globalNanos":1,
-            "value":1
-         },
-         {
-            "pulseId":3,
-            "iocMillis":3,
-            "iocNanos":3,
-            "globalMillis":3,
-            "globalNanos":3,
-            "value":3
-         }
-      ]
-   }
-]
-```
-
 ### Example Queries
 
 The following examples build on waveform data (see below). They also work for scalars (consider it as a waveform of length = 1) and images (waveform of length = dimX * dimY). 
@@ -337,6 +232,96 @@ The following examples build on waveform data (see below). They also work for sc
 
 ### Query Examples
 
+##### Query using compression
+
+```json
+{
+    "compression":"gzip",
+    "range":{
+        "startPulseId":0,
+        "endPulseId":3
+     },
+     "channels":[
+        "Channel_01"
+     ]
+}
+```
+
+or `deflate` can be used too:
+
+```json
+{
+    "compression":"deflate",
+    "range":{
+        "startPulseId":0,
+        "endPulseId":3
+     },
+     "channels":[
+        "Channel_01"
+     ]
+}
+```
+
+###### Command (gzip)
+
+The `curl` command has a `--compressed` option to decompress data automatically.
+
+```bash
+curl --compressed -H "Content-Type: application/json" -X POST -d '{"compression":"gzip","range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query
+```
+
+##### Query setting CSV response format
+
+```json
+{
+    "responseFormat":"csv",
+    "range":{
+        "startPulseId":0,
+        "endPulseId":4
+    },
+    "channels":[
+        "channel1",
+        "channel2"
+    ],
+    "fields":[
+        "channel",
+        "pulseId",
+        "iocMillis",
+        "iocNanos",
+        "globalMillis",
+        "globalNanos",
+        "shape",
+        "eventCount",
+        "value"
+    ]
+}
+```
+
+###### Command
+
+```bash
+curl -H "Content-Type: application/json" -X POST -d '{"responseFormat":"csv","range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"],"fields":["channel","pulseId","iocMillis","iocNanos","globalMillis","globalNanos","shape","eventCount","value"]}' http://data-api.psi.ch/sf/query
+```
+
+###### Response
+
+The response is in CSV.
+
+```text
+channel;pulseId;iocMillis;iocNanos;globalMillis;globalNanos;shape;eventCount;value
+testChannel1;0;0;0;0;0;[1];1;0
+testChannel1;1;10;0;10;0;[1];1;1
+testChannel1;2;20;0;20;0;[1];1;2
+testChannel1;3;30;0;30;0;[1];1;3
+testChannel1;4;40;0;40;0;[1];1;4
+testChannel2;0;0;0;0;0;[1];1;0
+testChannel2;1;10;0;10;0;[1];1;1
+testChannel2;2;20;0;20;0;[1];1;2
+testChannel2;3;30;0;30;0;[1];1;3
+testChannel2;4;40;0;40;0;[1];1;4
+``` 
+
+
 ##### Query by Pulse-Id Range
 
 ```json