From 2d0c0e27e04c05b9efe9b518a94fa6c6b88eb99f Mon Sep 17 00:00:00 2001
From: Benjamin Frost <bfrost.schule@gmail.com>
Date: Sun, 19 May 2024 20:30:16 +0200
Subject: [PATCH] docs: add docs for endpoints

---
 DOCS.md                         | 26 ++++++++++++++++++++++++++
 src/events/events.controller.ts |  6 +++---
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/DOCS.md b/DOCS.md
index 1ce203c..793614b 100644
--- a/DOCS.md
+++ b/DOCS.md
@@ -1,3 +1,29 @@
 # Session 4 API Documentation
 
 This is the API documentation for the AEC 2024 Skill 08 Session 4 API.
+
+## Events
+
+The API provides an endpoint to subscribe to events.
+
+### Subscribe to an Event
+
+This endpoint uses HTTP Long Polling, meaning the connection will remain open until an event is available. Clients should make a request to this endpoint and wait for a response. Once a response is received, the client should immediately make another request to continue receiving events.
+
+!!! note
+
+    For the initial request, it is possible to pass the query parameter `wait=false` to get the current event immediately.
+
+```
+GET /events/:id/subscribe
+```
+
+Example Response
+
+```json
+{
+  "action": {
+    "type": "flashlight"
+  }
+}
+```
diff --git a/src/events/events.controller.ts b/src/events/events.controller.ts
index ca7c322..8958f88 100644
--- a/src/events/events.controller.ts
+++ b/src/events/events.controller.ts
@@ -21,13 +21,13 @@ export class EventsController {
   poll(
     @Res() res: Response,
     @Param('id') id: string,
-    @Query('isInitialRequest') isInitialRequestParam: string,
+    @Query('wait') waitParam: string,
   ) {
     const event = events.find((e) => e.name === id);
     if (!event) throw new NotFoundException('Event not found');
 
-    const isInitialRequest = isInitialRequestParam === 'true';
-    if (isInitialRequest) {
+    const wait = waitParam === 'false';
+    if (wait) {
       return res.json(this.eventsService.getCurrentAction(event.name));
     }