aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/drafts/k2v-spec.md57
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/drafts/k2v-spec.md b/doc/drafts/k2v-spec.md
index 9d41b2c0..a335aee3 100644
--- a/doc/drafts/k2v-spec.md
+++ b/doc/drafts/k2v-spec.md
@@ -706,6 +706,63 @@ HTTP/1.1 200 OK
]
```
+**PollRange: `POST /<bucket>/<partition key>?poll_range`**, or alternatively<br/>
+**PollRange: `SEARCH /<bucket>/<partition key>?poll_range`**
+
+Polls a range of items for changes.
+
+The query body is a JSON object consisting of the following fields:
+
+| name | default value | meaning |
+|-----------------|---------------|----------------------------------------------------------------------------------------|
+| `prefix` | `null` | Restrict items to poll to those whose sort keys start with this prefix |
+| `start` | `null` | The sort key of the first item to poll |
+| `end` | `null` | The sort key of the last item to poll (excluded) |
+| `timeout` | 300 | The timeout before 304 NOT MODIFIED is returned if no value in the range is updated |
+| `seenMarker` | `null` | An opaque string returned by a previous PollRange call, that represents items already seen |
+
+The timeout can be set to any number of seconds, with a maximum of 600 seconds (10 minutes).
+
+The response is either:
+
+- A HTTP 304 NOT MODIFIED response with an empty body, if the timeout expired and no changes occurred
+
+- A HTTP 200 response, indicating that some changes have occurred since the last PollRange call, in which case a JSON object is returned in the body with the following fields:
+
+| name | meaning |
+|-----------------|----------------------------------------------------------------------------------------|
+| `seenMarker` | An opaque string that represents items already seen for future PollRange calls |
+| `items` | The list of items that have changed since last PollRange call, in the same format as ReadBatch |
+
+
+Example query:
+
+```json
+SEARCH /my_bucket?poll_range HTTP/1.1
+
+{
+ "prefix": "0391.",
+ "start": "0391.000001973107",
+ "seenMarker": "opaquestring123",
+}
+```
+
+
+Example response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "seenMarker": "opaquestring456",
+ "items": [
+ { sk: "0391.000001973221", ct: "opaquetoken123", v: ["b64cryptoblob123", "b64cryptoblob'123"] },
+ { sk: "0391.000001974191", ct: "opaquetoken456", v: ["b64cryptoblob456", "b64cryptoblob'456"] },
+ ]
+}
+```
+
## Internals: causality tokens