feat: new endpoint /instances/recent (#501)

* feat: new endpoint /instances/recent

* feat: add instances/recent paramaters

* refactor: split Locations from instances

* refactor: WorldID/InstanceID/LocationID

* fix: typo

* Clarify LocationID description

Updated description to clarify the meaning of LocationID.

---------

Co-authored-by: Aries <me@ariesclark.com>

Author: Hackebein

openapi/components/paths.yaml

@@ -281,6 +281,8 @@
 
 "/instances":
   $ref: "./paths/instances.yaml#/paths/~1instances"
+"/instances/recent":
+  $ref: "./paths/instances.yaml#/paths/~1instances~1recent"
 "/instances/{worldId}:{instanceId}":
   $ref: "./paths/instances.yaml#/paths/~1instances~1{worldId}:{instanceId}"
 "/instances/{worldId}:{instanceId}/shortName":

openapi/components/paths/instances.yaml

@@ -24,6 +24,24 @@ paths:
           $ref: ../responses/instances/InstanceResponse.yaml
         '401':
           $ref: ../responses/MissingCredentialsError.yaml
+  '/instances/recent':
+    get:
+      summary: List Recent Locations
+      tags:
+        - instances
+      parameters:
+        - $ref: ../parameters.yaml#/number
+        - $ref: ../parameters.yaml#/offset
+      operationId: getRecentLocations
+      security:
+        - authCookie: []
+      description: |-
+        Returns a list of recently visited locations.
+      responses:
+        '200':
+          $ref: ../responses/instances/LocationIDListResponse.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
   '/instances/{worldId}:{instanceId}':
     parameters:
       - $ref: ../parameters.yaml#/worldId

openapi/components/responses/instances/LocationIDListResponse.yaml

@@ -0,0 +1,7 @@
+description: Returns a list of LocationIDs.
+content:
+  application/json:
+    schema:
+      type: array
+      items:
+        $ref: ../../schemas/LocationID.yaml

openapi/components/schemas/CurrentUserPresence.yaml

@@ -42,7 +42,7 @@ properties:
     type: string
     nullable: true
   travelingToWorld:
-    $ref: ./WorldID.yaml
+    $ref: ./LocationID.yaml
     nullable: true
   userIcon:
     type: string

openapi/components/schemas/GroupInstance.yaml

@@ -2,11 +2,9 @@ title: GroupInstance
 type: object
 properties:
   instanceId:
-    type: string
-    minLength: 1
-    example: 12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)
-  location:
     $ref: ./InstanceID.yaml
+  location:
+    $ref: ./LocationID.yaml
   world:
     $ref: ./World.yaml
   memberCount:

openapi/components/schemas/Instance.yaml

@@ -38,14 +38,12 @@ properties:
   id:
     $ref: ./InstanceID.yaml
   instanceId:
-    type: string
-    minLength: 1
-    example: 12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)
+    $ref: ./InstanceID.yaml
   instancePersistenceEnabled:
     type: string
     nullable: true
   location:
-    $ref: ./InstanceID.yaml
+    $ref: ./LocationID.yaml
   n_users:
     type: integer
     minimum: 0

openapi/components/schemas/LocationID.yaml

@@ -0,0 +1,4 @@
+type: string
+example: 'wrld_4432ea9b-729c-46e3-8eaf-846aa0a37fdd:12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)'
+title: LocationID
+description: Represents a unique location, consisting of a world identifier and an instance identifier, or "offline" if the user is not on your friends list.

openapi/components/schemas/NotificationDetailInvite.yaml

@@ -2,7 +2,7 @@ properties:
   inviteMessage:
     type: string
   worldId:
-    $ref: ./WorldID.yaml
+    $ref: ./LocationID.yaml
   worldName:
     type: string
 required:

openapi/components/schemas/User.yaml

@@ -60,7 +60,7 @@ properties:
   last_platform:
     $ref: ./Platform.yaml
   location:
-    $ref: ./WorldID.yaml
+    $ref: ./LocationID.yaml
   note:
     type: string
   platform:

openapi/components/schemas/WorldID.yaml

@@ -1,4 +1,4 @@
-example: wrld_ba913a96-fac4-4048-a062-9aa5db092812
+example: wrld_4432ea9b-729c-46e3-8eaf-846aa0a37fdd
 title: WorldID
 type: string
 description: WorldID be "offline" on User profiles if you are not friends with that user.