api-contract.yml

openapi: 3.0.0
info:
  title: United Nest API
  description: This is the API Documentation of the United Nest REST API
  version: 1.0.0
servers:
  - url: http://localhost:4000/
    description: DEV Server
  - url: https://www.united-nest.com/
    description: PROD Server
paths: # TODO: add authentication methods for required endpoints
  # Add endpoints here

  # Signup endpoint
  /api/v1/auth/signup:
    post:
      description: "Creates a new user and returns the JWT token (logs the user in)"
      tags:
        - auth
      requestBody: # TODO: add example request payload
        description: "JSON Payload required for user signup"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                username:
                  type: string
                email:
                  type: string
                password:
                  type: string
                passwordConfirm:
                  type: string
                mobile:
                  type: number
              required:
                - name
                - username
                - email
                - mobile
                - password
                - passwordConfirm
      responses:
        "201":
          description: "User signup successful"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  token:
                    $ref: "#/components/schemas/tokenSchema"
                  data:
                    $ref: "#/components/schemas/userDocument"
        "400":
          description: "Invalid data submitted. Please view error message for more info"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Login endpoint
  /api/v1/auth/login:
    post:
      description: "Logs in a user(returns JWT) based on username/email/mobile and the password"
      tags:
        - auth
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/loginPayloadUsername"
                - $ref: "#/components/schemas/loginPayloadEmail"
                - $ref: "#/components/schemas/loginPayloadMobile"
      responses:
        "200":
          description: "OK, logged in successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  token:
                    $ref: "#/components/schemas/tokenSchema"
        "400":
          description: "Please provide both username|email|mobile & password"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "404":
          description: "User with given credentials not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Forgot Password endpoint
  /api/v1/auth/forgotPassword:
    post:
      description: "Sends a reset password link to the associated User(if that user exists)"
      tags:
        - auth
        - "User Account"
      requestBody: # TODO: add example request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
              required:
                - email
      responses:
        "200": # TODO: add example for this response
          description: "If a user with given email exists, the password reset link will be sent to that email"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Reset Password endpoint
  /api/v1/auth/resetPassword/{resetToken}:
    patch:
      description: "Resets the password of a user who has the given password reset token"
      tags:
        - auth
        - "User Account"
      parameters:
        - in: path
          name: resetToken
          schema:
            type: string
          required: true
          description: "Password Reset Token"
      requestBody: # TODO: add example request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                passwordConfirm:
                  type: string
              required:
                - password
                - passwordConfirm
      responses:
        "200": # TODO: add example for this response
          description: "OK. Reset Token valid and Password of the User is reset successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  message:
                    type: string
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Get Follow Requests endpoint
  /api/v1/connections/followRequests/{action}:
    get:
      description: "Returns all the pending Received|Sent Following Requests for the currently logged in user"
      tags:
        - "Connections"
      parameters:
        - in: path
          name: action
          schema:
            type: string
            enum: ["sent", "received"]
          required: true
      responses:
        "200":
          description: "Ok. Returns all pending request the user has sent|received, depending on action parameter value"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/connectionDocument"
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Send A Follow Request endpoint
  /api/v1/connections/followRequests/{username}:
    patch:
      description: "Sends a follow request to the specified user"
      tags:
        - "Connections"
      parameters:
        - in: path
          name: username
          description: "Intended user to whom the follow request goes to"
          schema:
            type: string
          required: true
      responses:
        "200": # TODO: add example for this response
          description: "OK. Follow Request Sent Successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  message:
                    type: string
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Accept A Follow Request endpoint
  /api/v1/connections/followRequests/{username}/{action}:
    patch:
      description: "Accept|Reject a follow request from the specified user"
      tags:
        - "Connections"
      parameters:
        - in: path
          name: username
          description: "Intended user who sent the follow request"
          schema:
            type: string
          required: true
        - in: path
          name: action
          description: "accept|reject"
          schema:
            type: string
            enum: ["accept", "reject"]
          required: true
      responses:
        "200": # TODO: add example for this response
          description: "OK. Follow Request has been accepted"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  message:
                    type: string
        "204":
          description: "OK. Follow Request has be rejected and corresponding record is deleted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/deleteDocumentSchema"
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Get All Following endpoint
  /api/v1/connections/following:
    get:
      description: "Return all exisiting users whom the current user is following"
      tags:
        - Connections
      responses:
        "200":
          description: "Ok, success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  results:
                    type: integer
                  data:
                    type: object
                    properties:
                      connections:
                        type: array
                        items:
                          $ref: "#/components/schemas/connectionDocument"
                required:
                  - status
                  - data
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Get All Followers endpoint
  /api/v1/connections/followers:
    get:
      description: "Return all exisiting users who are followers of current user"
      tags:
        - Connections
      responses:
        "200":
          description: "Ok, success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: "#/components/schemas/statusSchema"
                  results:
                    type: integer
                  data:
                    type: object
                    properties:
                      connections:
                        type: array
                        items:
                          $ref: "#/components/schemas/connectionDocument"
                required:
                  - status
                  - data
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

  # Unfollower User endpoint
  /api/v1/connections/following/{username}:
    delete:
      description: "Unfollow the specified user"
      tags:
        - Connections
      parameters:
        - in: path
          name: username
          schema:
            type: string
          required: true
      responses:
        "204":
          description: "Ok, unfollowed successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/deleteDocumentSchema"
        "400":
          description: "Client Side Error - Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "500":
          description: "Internal Server Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"

components:
  # Add Reusable schemas (data models) here
  schemas: # TODO: add examples to all schemas 😢
    # ** User Document sent to Frontend **
    userDocument:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        username:
          type: string
        email:
          type: string
        mobile:
          type: integer
        profilePhoto:
          type: string
        following:
          type: array
          items:
            type: string
        followers:
          type: array
          items:
            type: string
        pendingReqSent:
          type: array
          items:
            type: string
        pendingReqReceived:
          type: array
          items:
            type: string
        description:
          type: string
        role:
          type: string
          enum:
            - "user"
            - "merchant"
            - "admin"
        createdAt:
          type: string
        updatedAt:
          type: string

    # ** Generic Error Schema **
    error: # TODO: Change the Schema once you differentiate DEV & PROD errors in errorController.js
      type: object
      properties:
        status:
          $ref: "#/components/schemas/statusSchema"
        message:
          type: string

    # ** Login payload with username, password **
    loginPayloadUsername:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
      required:
        - username
        - password

    # ** Login payload with email, password **
    loginPayloadEmail:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
      required:
        - email
        - password

    # ** Login payload with email, password **
    loginPayloadMobile:
      type: object
      properties:
        mobile:
          type: integer
        password:
          type: string
      required:
        - mobile
        - password

    # ** response status (success|fail|error) **
    statusSchema:
      type: string
      enum:
        - success
        - fail
        - error

    # ** token (JWT) **
    tokenSchema:
      type: string

    # ** Follow (Connection) Document Schema **
    connectionDocument:
      type: object
      properties:
        requestSender:
          type: string
        requestReceiver:
          type: string
        requestSentTime:
          type: string
        status:
          type: string
          enum: ["success", "fail", "error"]
      required:
        - requestSender
        - requestReceiver
        - requestSentTime
        - status

    # ** Schema for Delete Request Response (204) **
    deleteDocumentSchema:
      type: object
      properties:
        status:
          type: string
          enum: ["success"]
      required:
        - status

  # Add Security scheme definitions (Authentication) here
  securitySchemes:
    # Authorization header: Bearer [TOKEN]
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorization header in the format 'Bearer [TOKEN]'"

    # Cookie Auth (unsafe, prone to CSRF attacks)
    cookieAuth:
      type: apiKey
      in: cookie
      name: token
      description: "JWT Token in the cookie"