From 193e68b9c93c8f0f07db6934137ed842fe88c5f5 Mon Sep 17 00:00:00 2001
From: Harold Dost <h.dost@criteo.com>
Date: Mon, 18 May 2020 10:16:02 +0200
Subject: [PATCH] documentation: Add Reference to the remote read API

- For now this is relatively simplistic, but at least acknowledges some
  of the basics, and points out some parts that might not be obvious at first.

Relates to #7192

Signed-off-by: Harold Dost <h.dost@criteo.com>
---
 docs/querying/remote_read_api.md | 87 ++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/querying/remote_read_api.md

diff --git a/docs/querying/remote_read_api.md b/docs/querying/remote_read_api.md
new file mode 100644
index 000000000..aae8e5d1b
--- /dev/null
+++ b/docs/querying/remote_read_api.md
@@ -0,0 +1,87 @@
+---
+title: Remote Read API
+sort_rank: 7
+---
+
+# Remote Read API
+
+This is not currently considered par of the stable API and is subject to change
+even between non-major version releases of Prometheus.
+
+## Format overview
+
+The API response format is JSON. Every successful API request returns a `2xx`
+status code.
+
+Invalid requests that reach the API handlers return a JSON error object
+and one of the following HTTP response codes:
+
+- `400 Bad Request` when parameters are missing or incorrect.
+- `422 Unprocessable Entity` when an expression can't be executed
+  ([RFC4918](https://tools.ietf.org/html/rfc4918#page-78)).
+- `503 Service Unavailable` when queries time out or abort.
+
+Other non-`2xx` codes may be returned for errors occurring before the API
+endpoint is reached.
+
+An array of warnings may be returned if there are errors that do
+not inhibit the request execution. All of the data that was successfully
+collected will be returned in the data field.
+
+The JSON response envelope format is as follows:
+
+```
+{
+  "status": "success" | "error",
+  "data": <data>,
+
+  // Only set if status is "error". The data field may still hold
+  // additional data.
+  "errorType": "<string>",
+  "error": "<string>",
+
+  // Only if there were warnings while executing the request.
+  // There will still be data in the data field.
+  "warnings": ["<string>"]
+}
+```
+
+Generic placeholders are defined as follows:
+
+* `<rfc3339 | unix_timestamp>`: Input timestamps may be provided either in
+[RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format or as a Unix timestamp
+in seconds, with optional decimal places for sub-second precision. Output
+timestamps are always represented as Unix timestamps in seconds.
+* `<series_selector>`: Prometheus [time series
+selectors](basics.md#time-series-selectors) like `http_requests_total` or
+`http_requests_total{method=~"(GET|POST)"}` and need to be URL-encoded.
+* `<duration>`: [Prometheus duration strings](basics.md#time_durations).
+For example, `5m` refers to a duration of 5 minutes.
+* `<bool>`: boolean values (strings `true` and `false`).
+
+Note: Names of query parameters that may be repeated end with `[]`.
+
+## Remote Read API
+
+This API provides data read functionality from Prometheus. This interface expects [snappy](https://github.com/google/snappy) compression.
+The API definition is located [here](https://github.com/prometheus/prometheus/blob/master/prompb/remote.proto).
+/// Can you clarify what you mean by this?
+/// https://github.com/prometheus/prometheus/pull/7266#discussion_r426456791 Can we talk a little bit how negotiation works of sampled vs streamed ?
+
+Request are made to the following endpoint.
+```
+/api/v1/read
+```
+
+### Samples
+/// Does it return a message that includes a list, or does it return a list of raw samples?
+
+This returns a message that includes a list of raw samples.
+
+### Streamed Chunks
+/// This is a little much detail, the relevant point is they're the internal implementation of the chunks.
+
+These streamed chunks utilize an XOR algorithm inspired by the [Gorilla](http://www.vldb.org/pvldb/vol8/p1816-teller.pdf)
+compression to encode the chunks. However, it provides resolution to the millisecond instead of to the second.
+
+