add docs/api-reference.md

2 files changed, 220 insertions, 0 deletions

diff --git a/docs/api-reference.md b/docs/api-reference.md
new file mode 100644
index 0000000..7f7a465
--- /dev/null
+++ b/docs/api-reference.md
@@ -0,0 +1,219 @@
+# REST API Reference
+
+## Collection type API
+
+### Create collection type entities
+
+You can create a new collection type entities. If the collection does not exist, it will automatically be created.
+
+The following call to `POST /api/rest/collection/entity` creates a new entity with fields `name` and `description`.
+
+```console
+curl -X POST http://localhost:8081/api/rest/collection/entity --data @- <<'EOF' | jq .
+{
+  "name": "Entity 1",
+  "description": "Description of entity 1"
+}
+EOF
+```
+
+Note that the created entity is returned, including the meta field `$fileName`.
+
+```json
+{
+  "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
+  "description": "Description of entity 1",
+  "name": "Entity 1"
+}
+```
+
+To demonstrate other API capabilities, go ahead and create a second entity.
+
+```console
+curl -X POST http://localhost:8081/api/rest/collection/entity --data @- <<'EOF' | jq .
+{
+  "name": "Entity 2",
+  "description": "Description of entity 2"
+}
+EOF
+```
+
+```json
+{
+  "$fileName": "ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json",
+  "description": "Description of entity 2",
+  "name": "Entity 2"
+}
+```
+
+### Retrieving a collection type's schema
+
+With having entities, a collection schema is automatically inferred, and can be queried.
+
+```console
+curl http://localhost:8081/api/rest/collection/entity/schema | jq .
+```
+
+As one would expect, the schema lists the fields `name`, `description` as required fields of type `string`.
+
+```json
+{
+  "$id": "entity.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "$fileName": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "$fileName",
+    "description",
+    "name"
+  ],
+  "title": "entity",
+  "type": "object"
+}
+```
+
+### Retrieving a single collection entity
+
+Single collection entities can be retrieved using their unique `$fileName` identifier.
+
+```console
+curl http://localhost:8081/api/rest/collection/entity/9474f0eb-06d7-4fd8-b89e-0ce996962508.json | jq .
+```
+
+TODO do not return list
+
+```json
+[
+  {
+    "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
+    "description": "Description of entity 1",
+    "name": "Entity 1"
+  }
+]
+```
+
+### Retrieving all collection entities
+
+All collection entities can be requested as well.
+
+```console
+curl http://localhost:8081/api/rest/collection/entity | jq .
+```
+
+```json
+[
+  {
+    "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
+    "description": "Description of entity 1",
+    "name": "Entity 1"
+  },
+  {
+    "$fileName": "ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json",
+    "description": "Description of entity 2",
+    "name": "Entity 2"
+  }
+]
+```
+
+### Updating a collection entity
+
+Updating a collection entity is possible by send only select fields.
+
+```console
+curl -X PUT http://localhost:8081/api/rest/collection/entity/ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json --data @- <<'EOF' | jq .
+{
+    "description": "Entity 2's description"
+}
+EOF
+```
+
+The endpoint returns the full, updated entity.
+
+TODO return full, updated entity, return single entity
+
+```json
+[]
+```
+
+Fields can be deleted setting them their values to `null`.
+
+```console
+curl -X PUT http://localhost:8081/api/rest/collection/entity/ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json --data @- <<'EOF' | jq .
+{
+    "description": null
+}
+EOF
+```
+
+Again, the response contains the full entity after the update.
+
+TODO return full, updated entity, return single entity
+
+```json
+[]
+```
+
+## Retrieving the global schema version
+
+Because we have deleted a required field, we have changed the `entity` collectiontype's schema.
+
+The collection type's schema endpoint reflects that change.
+
+```console
+curl http://localhost:8081/api/rest/collection/entity/schema | jq .
+```
+
+```json
+{
+  "$id": "entity.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "$fileName": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "$fileName",
+    "name"
+  ],
+  "title": "entity",
+  "type": "object"
+}
+```
+
+What's more, the global schema version records this backwards-incompatible (breaking) change.
+
+```console
+curl http://localhost:8081/api/rest/schemaVersion | jq .
+```
+
+```json
+"1.2.0"
+```
+
+### Deleting collection entities
+
+```console
+curl -X DELETE http://localhost:8081/api/rest/collection/entity/9474f0eb-06d7-4fd8-b89e-0ce996962508.json | jq .
+```
+
+TODO return deleted entity, only one entity
+
+```json
+[]
+```
diff --git a/tests.nix b/tests.nix
index c7955fb..f442a54 100644
--- a/tests.nix
+++ b/tests.nix
@@ -79,5 +79,6 @@ let
   '';
 in
 {
+  api-reference = makeDocTest "api-reference" ./docs/api-reference.md;
   get-started-cli = makeDocTest "get-started-cli" ./docs/get-started-cli.md;
 }