feat(api-reference): finish Cache api reference

hyper63 · Jan 2, 2024 · e527123 · e527123
1 parent fa5435f
commit e527123
Showing 1 changed file with 185 additions and 0 deletions.
diff --git a/src/docs/api-reference/rest/cache.md b/src/docs/api-reference/rest/cache.md
@@ -109,3 +109,188 @@ curl -X DELETE https://$HOST/cache/$DOMAIN
 | ------ | :--------------------------------: | ---------------------------: |
 | 201    |  The `Cache` Service was created   |               `{ ok: true }` |
 | 404    | The `Cache` Service does not exist | `{ ok: false, status: 404 }` |
+
+## Cache a Document
+
+Store a Document in the `Cache` Service at the specified `key`
+
+A hyper `Data` Service document is a JSON document with one to many fields. An `_id` field is allowed. If an `_id` is not provided, it will be generated by the hyper `Server`. The `_id` field MUST be unique.
+
+::: code-group
+
+```js [node.js]
+import { connect } from 'hyper-connect'
+
+const { cache } = connect(process.env.HYPER)
+
+await cache.add('movie-1', { _id: "...", ... }, '2h') // { ok: true }
+```
+
+```sh [curl]
+export HOST="hyper.host"
+export DOMAIN="foobar"
+
+curl -X POST https://$HOST/cache/$DOMAIN
+ -H 'Content-Type: application/json' \
+ -d '{ "key": "movie-1", "value": { "_id": "...", "title": "Ghostbusters", "year": "1984", "type": "movie" }, "ttl": "2h" }'
+```
+
+### Input
+
+| Field   | Type [optional] |                                                                                   Description |
+| ------- | :-------------: | --------------------------------------------------------------------------------------------: |
+| `key`   |     string      |                                                            The `key` to store the document at |
+| `value` |     object      |                                                                     The document to be stored |
+| `ttl`   |    [string]     | The Time-To-Live for the cached value. If not provided, then the value is cached indefinitely |
+
+#### `ttl` Format
+
+The `ttl` provided should follow the format `XY` where `X` is a number, and `Y` is a single character representing a unit of time:
+
+`s`: `seconds`
+`m`: `minutes`
+`h`: `hours`
+`d`: `days`
+`w`: `weeks`
+`y`: `years`
+
+Eg. `10s`, `15m`, `5h`, `2d`, `1w`, `1y`
+
+:::
+
+### Common Responses
+
+| Status |                  Description                  |                     Response |
+| ------ | :-------------------------------------------: | ---------------------------: |
+| 201    |           The document was created            |               `{ ok: true }` |
+| 409    | A document stored at the `key` already exists | `{ ok: false, status: 409 }` |
+
+## Retrieve a Document
+
+Retrieve a Document in the `Cache` Service at the specified `key`
+
+::: code-group
+
+```js [node.js]
+import { connect } from "hyper-connect";
+
+const { cache } = connect(process.env.HYPER);
+
+await cache.get("movie-1"); // { ok: true, doc: {...} }
+```
+
+```sh [curl]
+export HOST="hyper.host"
+export DOMAIN="foobar"
+
+curl -X GET https://$HOST/cache/$DOMAIN/movie-1
+```
+
+:::
+
+### Common Responses
+
+| Status |                                     Description                                     |                     Response |
+| ------ | :---------------------------------------------------------------------------------: | ---------------------------: |
+| 201    |                              The document was created                               |   `{ ok: true, doc: {...} }` |
+| 404    | A document stored at the `key` does not exist or the `Cache` Service does not exist | `{ ok: false, status: 404 }` |
+
+## Replace a Document
+
+Replace a Document in the `Cache` Service at the specified `key`. This operation REPLACES the document, so the entire document must be provided.
+
+::: code-group
+
+```js [node.js]
+import { connect } from 'hyper-connect'
+
+const { cache } = connect(process.env.HYPER)
+
+await cache.set('movie-1', { _id: "...", ... }, '2h') // { ok: true }
+```
+
+```sh [curl]
+export HOST="hyper.host"
+export DOMAIN="foobar"
+
+curl -X PUT https://$HOST/cache/$DOMAIN/movie-1?ttl=2h
+ -H 'Content-Type: application/json' \
+ -d '{ "_id": "...", "title": "Ghostbusters", "year": "1984", "type": "movie" }'
+```
+
+See [`ttl` Format](#ttl-format) on how to format the `ttl` if provided.
+
+:::
+
+### Common Responses
+
+| Status |            Description             |                     Response |
+| ------ | :--------------------------------: | ---------------------------: |
+| 200    |      The document was created      |               `{ ok: true }` |
+| 404    | The `Cache` Service does not exist | `{ ok: false, status: 404 }` |
+
+## Remove a Document
+
+Remove a Document in the `Cache` Service at the specified `key`.
+
+::: code-group
+
+```js [node.js]
+import { connect } from "hyper-connect";
+
+const { cache } = connect(process.env.HYPER);
+
+await cache.remove("movie-1"); // { ok: true }
+```
+
+```sh [curl]
+export HOST="hyper.host"
+export DOMAIN="foobar"
+
+curl -X DELETE https://$HOST/cache/$DOMAIN/movie-1
+```
+
+:::
+
+### Common Responses
+
+| Status |                                     Description                                     |                     Response |
+| ------ | :---------------------------------------------------------------------------------: | ---------------------------: |
+| 200    |                              The document was removed                               |               `{ ok: true }` |
+| 404    | A document stored at the `key` does not exist or the `Cache` Service does not exist | `{ ok: false, status: 404 }` |
+
+## Query a `Cache` Service
+
+Query the `Cache` Service for all key-value pairs, whose `key` matches the provided `pattern`. Using the `*` wildcard, you can define patterns that match all the key-values that either start with the provided pattern, end with the pattern, or is in-between the pattern.
+
+For example `movie-*`, `*-1984`, or `movie*1984`
+
+:::tip
+Remember, you `Cache` Service `key`s do not need to be strictly `_id` from a hyper `Data` Service. They can be anything! You can store more information in your `key`s, such that a pattern can fetch multiple cached documents in a single request.
+:::
+
+::: code-group
+
+```js [node.js]
+import { connect } from "hyper-connect";
+
+const { cache } = connect(process.env.HYPER);
+
+await cache.query("movie*"); // { ok: true, docs: [ { key: 'movie-5', value: {...} } ] }
+```
+
+```sh [curl]
+export HOST="hyper.host"
+export DOMAIN="foobar"
+
+curl -X POST|GET https://$HOST/cache/$DOMAIN/_query?pattern=movie*
+```
+
+:::
+
+### Common Responses
+
+| Status |            Description             |                                                  Response |
+| ------ | :--------------------------------: | --------------------------------------------------------: |
+| 200    |      The query was successful      | `{ ok: true, docs: [ { key: 'movie-5', value: {...} } ]}` |
+| 404    | The `Cache` Service does not exist |                              `{ ok: false, status: 404 }` |