openapi.yaml

openapi: 3.0.3
info:
  title: Budget Management API
  version: 1.0.0
  description: >
    A comprehensive backend API for managing budgets, expenses, orders, transactions, notifications, and user authentication/management.
  contact:
    name: Son Nguyen
    url: https://example.com
    email: son.nguyen@example.com
servers:
  - url: https://budget-management-backend-api.onrender.com
    description: Production Server

tags:
  - name: Auth
    description: Authentication and User Management
  - name: Budgets
    description: Budget Management
  - name: Customers
    description: Customer Management
  - name: Expenses
    description: Expense Management
  - name: Notifications
    description: Real-Time Notifications
  - name: Orders
    description: Order Management
  - name: Search
    description: Search Expenses via Elasticsearch
  - name: Tasks
    description: Task Management (RabbitMQ, Redis)
  - name: Transactions
    description: Transaction Logs Management (PostgreSQL)
  - name: Users
    description: User Profiles

paths:
  /api/auth/register:
    post:
      tags:
        - Auth
      summary: Register a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, email, password]
              properties:
                username:
                  type: string
                  example: "john_doe"
                email:
                  type: string
                  format: email
                  example: "john.doe@example.com"
                password:
                  type: string
                  format: password
                  example: "P@ssw0rd!"
      responses:
        '201':
          description: User registered successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Registration successful"
        '400':
          description: Validation error or email in use.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Registration failed. Maybe email already in use."
        '500':
          description: Server error.

  /api/auth/login:
    post:
      tags:
        - Auth
      summary: Authenticate a user and return a JWT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                  example: "john.doe@example.com"
                password:
                  type: string
                  format: password
                  example: "P@ssw0rd!"
      responses:
        '200':
          description: Login successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Login successful"
                  token:
                    type: string
                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
        '401':
          description: Invalid email or password.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Invalid email or password."
        '500':
          description: Server error.

  /api/auth/logout:
    post:
      tags:
        - Auth
      summary: Logout a user and invalidate all tokens
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User logged out successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Logout successful"
        '401':
          description: Unauthorized or token invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Token invalid or not provided"
        '500':
          description: Server error.

  /api/auth/verify-email:
    post:
      tags:
        - Auth
      summary: Verify if an email is registered
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                  example: "john.doe@example.com"
      responses:
        '200':
          description: Email verification result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  registered:
                    type: boolean
                    example: true
        '500':
          description: Server error.

  /api/auth/reset-password:
    post:
      tags:
        - Auth
      summary: Reset a user's password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, newPassword]
              properties:
                email:
                  type: string
                  format: email
                newPassword:
                  type: string
                  format: password
      responses:
        '200':
          description: Password reset successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Password reset successful."
        '404':
          description: User not found.
        '500':
          description: Server error.

  /api/auth/verify-token:
    post:
      tags:
        - Auth
      summary: Verify if a token is valid
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
      responses:
        '200':
          description: Token is valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
        '401':
          description: Token is invalid or expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Token is invalid or expired"
        '500':
          description: Server error.

  /api/budgets:
    post:
      tags:
        - Budgets
      summary: Create a new budget
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BudgetInput"
      responses:
        '201':
          description: Budget created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Budget"
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    get:
      tags:
        - Budgets
      summary: Get all budgets
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of all budgets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Budget"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/budgets/{id}:
    get:
      tags:
        - Budgets
      summary: Get a budget by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Budget retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Budget"
        '404':
          description: Budget not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    delete:
      tags:
        - Budgets
      summary: Delete a budget by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Budget deleted successfully.
        '404':
          description: Budget not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    put:
      tags:
        - Budgets
      summary: Update a budget by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BudgetInput"
      responses:
        '200':
          description: Budget updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Budget"
        '404':
          description: Budget not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/customers:
    post:
      tags:
        - Customers
      summary: Create a new customer
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerInput"
      responses:
        '201':
          description: Customer created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    get:
      tags:
        - Customers
      summary: Retrieve a list of all customers
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of all customers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Customer"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/customers/{id}:
    get:
      tags:
        - Customers
      summary: Retrieve a customer by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Customer retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
        '404':
          description: Customer not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    delete:
      tags:
        - Customers
      summary: Delete a customer by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Customer deleted successfully.
        '404':
          description: Customer not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    put:
      tags:
        - Customers
      summary: Update a customer by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerInput"
      responses:
        '200':
          description: Customer updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
        '404':
          description: Customer not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/expenses:
    post:
      tags:
        - Expenses
      summary: Add a new expense to a budget
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExpenseInput"
      responses:
        '201':
          description: Expense added successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Expense"
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '404':
          description: Budget not found.
        '500':
          description: Server error.

    get:
      tags:
        - Expenses
      summary: Retrieve all expenses across all budgets
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of all expenses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Expense"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/expenses/{budgetId}:
    get:
      tags:
        - Expenses
      summary: Retrieve all expenses for a specific budget
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: budgetId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of expenses for the given budget.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Expense"
        '401':
          description: Unauthorized.
        '404':
          description: Budget not found.
        '500':
          description: Server error.

  /api/expenses/{id}:
    delete:
      tags:
        - Expenses
      summary: Delete an expense by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Expense deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Expense not found.
        '500':
          description: Server error.

    put:
      tags:
        - Expenses
      summary: Update an expense by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExpenseInput"
      responses:
        '200':
          description: Expense updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Expense"
        '401':
          description: Unauthorized.
        '404':
          description: Expense not found.
        '500':
          description: Server error.

  /api/notifications/send:
    post:
      tags:
        - Notifications
      summary: Send a real-time notification
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  example: "64c9f8f2a73c2f001b3c68f4"
                message:
                  type: string
                  example: "You have a new expense!"
      responses:
        '200':
          description: Notification sent successfully.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/orders:
    post:
      tags:
        - Orders
      summary: Create a new order
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderInput"
      responses:
        '201':
          description: Order created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    get:
      tags:
        - Orders
      summary: Retrieve all orders
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of all orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/orders/{id}:
    get:
      tags:
        - Orders
      summary: Retrieve an order by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        '404':
          description: Order not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    delete:
      tags:
        - Orders
      summary: Delete an order by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order deleted successfully.
        '404':
          description: Order not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    put:
      tags:
        - Orders
      summary: Update an order by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderInput"
      responses:
        '200':
          description: Order updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        '404':
          description: Order not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/search:
    post:
      tags:
        - Search
      summary: Search expenses in Elasticsearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query, page, size]
              properties:
                query:
                  type: string
                page:
                  type: integer
                size:
                  type: integer
      responses:
        '200':
          description: Search results returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  page:
                    type: integer
                  size:
                    type: integer
                  expenses:
                    type: array
                    items:
                      $ref: "#/components/schemas/Expense"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/tasks:
    post:
      tags:
        - Tasks
      summary: Submit a task to RabbitMQ
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description]
              properties:
                description:
                  type: string
      responses:
        '201':
          description: Task submitted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    get:
      tags:
        - Tasks
      summary: Retrieve all tasks
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of tasks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Task"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/tasks/{id}:
    get:
      tags:
        - Tasks
      summary: Check the status of a task
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        '404':
          description: Task not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    delete:
      tags:
        - Tasks
      summary: Delete a task
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task deleted.
        '404':
          description: Task not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    put:
      tags:
        - Tasks
      summary: Update a task by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                status:
                  type: string
                  enum: [pending, completed]
      responses:
        '200':
          description: Task updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        '404':
          description: Task not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/transactions:
    post:
      tags:
        - Transactions
      summary: Add a new transaction log
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionInput"
      responses:
        '201':
          description: Transaction added.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    get:
      tags:
        - Transactions
      summary: Retrieve all transaction logs
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of all transaction logs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: "#/components/schemas/Transaction"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/transactions/user/{userId}:
    get:
      tags:
        - Transactions
      summary: Retrieve transaction logs by user ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transactions retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Transaction"
        '401':
          description: Unauthorized.
        '404':
          description: User or transactions not found.
        '500':
          description: Server error.

  /api/transactions/{id}:
    delete:
      tags:
        - Transactions
      summary: Delete a transaction log by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction deleted.
        '404':
          description: Transaction not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

    put:
      tags:
        - Transactions
      summary: Update a transaction log by ID
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionInput"
      responses:
        '200':
          description: Transaction updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        '404':
          description: Transaction not found.
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

  /api/users/profile:
    get:
      tags:
        - Users
      summary: Get the profile of the currently authenticated user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '401':
          description: Token missing or invalid.
        '404':
          description: User not found.
        '500':
          description: Server error.

    put:
      tags:
        - Users
      summary: Update the profile of the currently authenticated user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Profile updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '401':
          description: Unauthorized.
        '404':
          description: User not found.
        '500':
          description: Server error.

    patch:
      tags:
        - Users
      summary: Partially update the profile of the currently authenticated user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Profile updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '401':
          description: Unauthorized.
        '404':
          description: User not found.
        '500':
          description: Server error.

  /api/users:
    get:
      tags:
        - Users
      summary: Retrieve all user profiles
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of all user profiles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        '401':
          description: Unauthorized.
        '500':
          description: Server error.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Budget:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        limit:
          type: number
        createdAt:
          type: string
          format: date-time
      example:
        _id: "67650ee2dce934e18b2c7884"
        name: "Travel"
        limit: 2000

    BudgetInput:
      type: object
      required: [name, limit]
      properties:
        name:
          type: string
        limit:
          type: number

    Customer:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string

    CustomerInput:
      type: object
      required: [name, email, phone]
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string

    Expense:
      type: object
      properties:
        _id:
          type: string
        budgetId:
          type: string
        description:
          type: string
        amount:
          type: number
        createdAt:
          type: string
          format: date-time

    ExpenseInput:
      type: object
      required: [budgetId, description, amount]
      properties:
        budgetId:
          type: string
        description:
          type: string
        amount:
          type: number

    Order:
      type: object
      properties:
        _id:
          type: string
        customerId:
          type: string
        amount:
          type: number
        status:
          type: string
          enum: [pending, completed, shipped, delivered, canceled]

    OrderInput:
      type: object
      required: [customerId, amount]
      properties:
        customerId:
          type: string
        amount:
          type: number
        status:
          type: string
          enum: [pending, completed, shipped, delivered, canceled]

    Task:
      type: object
      properties:
        _id:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [pending, completed]

    Transaction:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: string
        description:
          type: string
        amount:
          type: string
        budget_id:
          type: string
        created_at:
          type: string
          format: date-time

    TransactionInput:
      type: object
      required: [user_id, description, amount, budget_id]
      properties:
        user_id:
          type: string
        description:
          type: string
        amount:
          type: number
        budget_id:
          type: string

    User:
      type: object
      properties:
        _id:
          type: string
        username:
          type: string
        email:
          type: string