Split out Friends API

openapi/components/paths/friends.yaml

@@ -0,0 +1,107 @@
+openapi: 3.0.3
+info:
+  title: friends
+  version: '1.0'
+  description: A
+paths:
+  /auth/user/friends:
+    get:
+      summary: List Friends
+      tags:
+        - friends
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: ../schemas/LimitedUser.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+      operationId: getFriends
+      security:
+        - apiKeyCookie: []
+          authCookie: []
+      parameters:
+        - $ref: ../../openapi.yaml#/components/parameters/offset
+        - $ref: ../../openapi.yaml#/components/parameters/number
+        - $ref: ../../openapi.yaml#/components/parameters/offline
+      description: List information about friends.
+  '/user/{userId}/friendStatus':
+    parameters:
+      - $ref: ../../openapi.yaml#/components/parameters/userId
+    get:
+      summary: Check Friend Status
+      tags:
+        - friends
+      responses:
+        '200':
+          $ref: ../responses/friends/FriendStatusResponse.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+      operationId: getFriendStatus
+      security:
+        - apiKeyCookie: []
+          authCookie: []
+      description: 'Retrieve if the user is currently a friend with a given user, if they have an outgoing friend request, and if they have an incoming friend request. The proper way to receive and accept friend request is by checking if the user has an incoming `Notification` of type `friendRequest`, and then accepting that notification.'
+  '/user/{userId}/friendRequest':
+    parameters:
+      - $ref: ../../openapi.yaml#/components/parameters/userId
+    post:
+      summary: Send Friend Request
+      tags:
+        - friends
+      operationId: friend
+      description: Send a friend request to another user.
+      security:
+        - apiKeyCookie: []
+          authCookie: []
+      responses:
+        '200':
+          $ref: ../responses/notifications/NotificationResponse.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+        '404':
+          $ref: ../responses/friends/UserDoesntExistError.yaml
+    delete:
+      summary: Delete Friend Request
+      tags:
+        - friends
+      operationId: deleteFriendRequest
+      description: 'Deletes an outgoing pending friend request to another user. To delete an incoming friend request, use the `deleteNotification` endpoint instead.'
+      security:
+        - apiKeyCookie: []
+          authCookie: []
+      responses:
+        '200':
+          $ref: ../responses/friends/DeleteFriendSuccess.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+        '404':
+          $ref: ../responses/friends/DeleteFriendError.yaml
+  '/auth/user/friends/{userId}':
+    parameters:
+      - $ref: ../../openapi.yaml#/components/parameters/userId
+    delete:
+      summary: Unfriend
+      operationId: unfriend
+      responses:
+        '200':
+          $ref: ../responses/friends/UnfriendSuccess.yaml
+        '400':
+          $ref: ../responses/friends/NotFriendsError.yaml
+        '401':
+          $ref: ../responses/MissingCredentialsError.yaml
+      description: Unfriend a user by ID.
+      security:
+        - apiKeyCookie: []
+          authCookie: []
+      tags:
+        - friends
+tags:
+  $ref: ../../openapi.yaml#/tags
+components:
+  securitySchemes:
+    $ref: ../../openapi.yaml#/components/securitySchemes

openapi/components/responses/friends/DeleteFriendError.yaml

@@ -0,0 +1,11 @@
+description: Error response when trying to delete a non-existent friend-request.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Error.yaml
+    examples:
+      404 Delete Friend Request:
+        value:
+          error:
+            message: that friend request could not be found
+            status_code: 404

openapi/components/responses/friends/DeleteFriendSuccess.yaml

@@ -0,0 +1,11 @@
+description: Successful response after cancelling a friend request.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Success.yaml
+    examples:
+      Deleted Friend Request:
+        value:
+          success:
+            message: Friendship request deleted
+            status_code: 200

openapi/components/responses/friends/FriendStatusResponse.yaml

@@ -0,0 +1,16 @@
+description: Returns a users Friend Status.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/FriendStatus.yaml
+    examples:
+      Not Friends:
+        value:
+          isFriend: true
+          outgoingRequest: false
+          incomingRequest: false
+      Is Friend:
+        value:
+          isFriend: true
+          outgoingRequest: false
+          incomingRequest: false

openapi/components/responses/friends/NotFriendsError.yaml

@@ -0,0 +1,11 @@
+description: Error response when trying to unfriend someone who is not a friend.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Error.yaml
+    examples:
+      400 Not Friends Response:
+        value:
+          error:
+            message: These users are not friends
+            status_code: 400

openapi/components/responses/friends/UnfriendSuccess.yaml

@@ -0,0 +1,11 @@
+description: Successful response after unfriending a user.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Success.yaml
+    examples:
+      Unfriend Success:
+        value:
+          success:
+            message: Friendship destroyed
+            status_code: 200

openapi/components/responses/friends/UserDoesntExistError.yaml

@@ -0,0 +1,11 @@
+description: Error response when trying to send a friend request to a user which doesn't exist.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Error.yaml
+    examples:
+      404 User Doesn't Exist Response:
+        value:
+          error:
+            message: user doesn't existǃ
+            status_code: 404

openapi/components/responses/notifications/NotificationResponse.yaml

@@ -0,0 +1,16 @@
+description: Returns a single Notifcation object.
+content:
+  application/json:
+    schema:
+      $ref: ../../schemas/Notification.yaml
+    examples:
+      Example Friend Request Response:
+        value:
+          id: frq_00000000-0000-0000-0000-000000000000
+          senderUserId: usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469
+          senderUsername: tupper
+          type: friendRequest
+          message: ''
+          details: '{}'
+          seen: false
+          created_at: '2021-01-01T00:00:00.000Z'

openapi/components/schemas/FriendStatus.yaml

@@ -0,0 +1,16 @@
+title: Friend Status
+type: object
+properties:
+  isFriend:
+    type: boolean
+    default: false
+  outgoingRequest:
+    type: boolean
+    default: false
+  incomingRequest:
+    type: boolean
+    default: false
+required:
+  - isFriend
+  - outgoingRequest
+  - incomingRequest