From 5e84213baf821fdd0e2dae48c43a1225f096049f Mon Sep 17 00:00:00 2001
From: jellejurre <jelle@jilles.com>
Date: Mon, 11 Nov 2024 18:36:45 +0100
Subject: [PATCH] Add User Group Instances endpoint

---
 openapi/components/paths.yaml                  |  2 ++
 openapi/components/paths/users.yaml            | 18 ++++++++++++++++++
 .../users/UserGroupInstanceListResponse.yaml   | 13 +++++++++++++
 .../responses/users/UserMustBeOwnError.yaml    | 11 +++++++++++
 4 files changed, 44 insertions(+)
 create mode 100644 openapi/components/responses/users/UserGroupInstanceListResponse.yaml
 create mode 100644 openapi/components/responses/users/UserMustBeOwnError.yaml

diff --git a/openapi/components/paths.yaml b/openapi/components/paths.yaml
index 9ffaee7a..afe4d986 100644
--- a/openapi/components/paths.yaml
+++ b/openapi/components/paths.yaml
@@ -244,6 +244,8 @@
   $ref: "./paths/users.yaml#/paths/~1users~1{userId}~1groups~1requested"
 "/users/{userId}/groups/represented":
   $ref: "./paths/users.yaml#/paths/~1users~1{userId}~1groups~1represented"
+"/users/{userId}/instances/groups":
+  $ref: "./paths/users.yaml#/paths/~1users~1{userId}~1instances~1groups"
 
 # worlds
 
diff --git a/openapi/components/paths/users.yaml b/openapi/components/paths/users.yaml
index 6ac58b33..2728898d 100644
--- a/openapi/components/paths/users.yaml
+++ b/openapi/components/paths/users.yaml
@@ -194,6 +194,24 @@ paths:
           $ref: ../responses/MissingCredentialsError.yaml
       security:
         - authCookie: []
+  "/users/{userId}/instances/groups":
+    parameters:
+      - $ref: ../parameters.yaml#/userId
+    get:
+      summary: Get User Group Instances
+      description: Returns a list of group instances for a user
+      operationId: getUserGroupInstances
+      tags:
+        - users
+      responses:
+        '200':
+          $ref: ../responses/users/UserGroupInstanceListResponse.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+        '403':
+          $ref: ../responses/users/UserMustBeOwnError.yaml
+      security:
+        - authCookie: []
 tags:
   $ref: ../tags.yaml
 components:
diff --git a/openapi/components/responses/users/UserGroupInstanceListResponse.yaml b/openapi/components/responses/users/UserGroupInstanceListResponse.yaml
new file mode 100644
index 00000000..68234e7b
--- /dev/null
+++ b/openapi/components/responses/users/UserGroupInstanceListResponse.yaml
@@ -0,0 +1,13 @@
+description: Returns a list of Instance objects with a fetched at time.
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        fetchedAt:
+          type: string
+          format: date-time
+        instances:
+          type: array
+          items:
+            $ref: ../../schemas/Instance.yaml
diff --git a/openapi/components/responses/users/UserMustBeOwnError.yaml b/openapi/components/responses/users/UserMustBeOwnError.yaml
new file mode 100644
index 00000000..de4ea273
--- /dev/null
+++ b/openapi/components/responses/users/UserMustBeOwnError.yaml
@@ -0,0 +1,11 @@
+description: Error response when trying get group instances of another user.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Error.yaml
+    examples:
+      User Id must be your own:
+        value:
+          error:
+            message: "User ID must be your own․"
+            status_code: 403
\ No newline at end of file