From 6164b1e34dca95291863ad588bece4e3a88edfb4 Mon Sep 17 00:00:00 2001
From: Timon Borter <timon.borter@gmx.ch>
Date: Sun, 5 Nov 2023 17:41:33 +0100
Subject: [PATCH] docs: rest api

---
 .../src/main/asciidoc/concepts.adoc           |  1 +
 .../src/main/asciidoc/rest-api.adoc           | 52 +++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 simulator-docs/src/main/asciidoc/rest-api.adoc

diff --git a/simulator-docs/src/main/asciidoc/concepts.adoc b/simulator-docs/src/main/asciidoc/concepts.adoc
index 6f1243061..2ee1e8d99 100644
--- a/simulator-docs/src/main/asciidoc/concepts.adoc
+++ b/simulator-docs/src/main/asciidoc/concepts.adoc
@@ -153,6 +153,7 @@ The simulator automatically loads Spring beans defined in the following location
 All beans delineated within these files are seamlessly integrated into the simulator's Spring application context upon loading. This process ensures that all necessary configurations are applied to facilitate the desired behavior of the simulator.
 Furthermore, customizations and additional beans can be added to adapt to more complex scenarios or to extend the simulator's capabilities beyond its default configuration set.
 
+include::rest-api.adoc[]
 include::scenario-mapper.adoc[]
 include::scenarios.adoc[]
 include::intermediate-messages.adoc[]
diff --git a/simulator-docs/src/main/asciidoc/rest-api.adoc b/simulator-docs/src/main/asciidoc/rest-api.adoc
new file mode 100644
index 000000000..c8f23b4b4
--- /dev/null
+++ b/simulator-docs/src/main/asciidoc/rest-api.adoc
@@ -0,0 +1,52 @@
+[[rest-api]]
+== REST API
+
+The simulator comes with an extensive REST API.
+Each single entity can be listed and searched through using it.
+The following default resources are present:
+
+* `/api/messages`
+* `/api/message-headers`
+* `/api/scenario-actions`
+* `/api/scenario-executions`
+* `/api/scenario-parameters`
+* `/api/test-parameters`
+* `/api/test-results`
+
+For each of the listed resources it is possible to:
+
+* List ALL results using a `GET /` request to the root URI
+    * Pagination is possible
+    * Filtering is possible
+* Simply count ALL results using the `GET /count` endpoint
+* Receive a SINGLE resource when calling the `GET /{id}` endpoint
+
+All REST resources follow this pattern, except a few listed in the following chapter.
+
+[[receive-single-test-result]]
+=== Receive SINGLE Test-Parameter
+
+The `TestParameter` entity is identified by a composite key, consisting of the `TestResult` ID and the `TestParameter` key.
+Therefore, in order to receive a SINGLE `TestParameter` use can use the `GET /{testResultId}/{key}` endpoint.
+
+[[scenario-resource]]
+=== Scenario Resource
+
+The `Scenario` REST resource is an exception as well.
+By default, the `GET /` endpoint returns a list of scenarios.
+The mainly consist of their unique name, although they each also have a type indicating if it is a `SimulatorScenario` (type: `MESSAGE_TRIGGERED`) or `ScenarioStarter` (type: `STARTER`).
+The REST resource supports pagination, but not filtering.
+
+This REST resource has no SINGLE resource endpoint, because that would not offer any more details.
+However, you can directly see the parameters of a scenario when calling the `GET /{scenarioName}/parameters` endpoint.
+
+Additionally, you can launch scenarios using the `POST /{scenarioName}/launch` endpoint.
+It accepts an array of scenario parameters in the request body.
+
+[[rest-api-pagination]]
+=== Pagination
+
+
+
+[[rest-api-filtering]]
+=== Filtering