MyINPulse/documentation/openapi/src/adminApi.yaml

# Admin API Endpoints
paths:
  /admin/projects:
    get:
      operationId: getAdminProjects
      summary: Get projects associated with the admin
      tags:
        - Admin API
      security:
        - MyINPulse: [MyINPulse-admin]
      description: Retrieves a list of projects managed by the requesting admin, including key details for overview.
      responses:
        "200":
          description: OK - List of projects returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./main.yaml#/components/schemas/project"
        "400":
          description: Bad Request - Invalid project data provided (e.g., missing required fields).
        "401":
          description: Unauthorized - Authentication required or invalid token.
          
    post:
      operationId: addProjectManually
      summary: Manually add a new project
      description: Creates a new project with the provided details. 
      tags:
        - Admin API
      security:
        - MyINPulse: [MyINPulse-admin]
      requestBody:
        required: true
        description: Project details to create. `idProject` and `creationDate` will be ignored if sent and set by the server.
        content:
          application/json:
            schema:
              $ref: "./main.yaml#/components/schemas/project"
      responses:
        "201": # Use 201 Created for successful creation
          description: Created - Project added successfully. Returns the created project.
          content:
            application/json:
              schema:
                $ref: "./main.yaml#/components/schemas/project"
        "400":
          description: Bad Request - Invalid project data provided (e.g., missing required fields).
        "401":
          description: Unauthorized.
          

  /admin/projects/pending:
    get:
      operationId: getPendingProjects
      summary: Get projects awaiting validation
      tags:
        - Admin API
      security:
        - MyINPulse: [MyINPulse-admin]
      description: Retrieves a list of projects submitted by entrepreneurs that are pending admin approval.
      responses:
        "200":
          description: OK - List of pending projects returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./main.yaml#/components/schemas/project" # Assuming pending projects use the same schema
        "401":
          description: Unauthorized.        

  /admin/projects/pending/decision/{pendingProjectId}:
    post:
      operationId: decidePendingProject
      summary: Approve or reject a pending project
      tags:
        - Admin API
      description: |-
        Allows an admin to make a decision on a project awaiting validation.
        If approved (decision=true), the project status changes, and it's linked to the involved users.
        If rejected (decision=false), the pending project data might be archived or deleted based on business logic.
      security:
          - MyINPulse: [MyINPulse-admin]
      parameters:
        - in: path
          name: pendingProjectId # Corrected typo and name change
          required: true
          schema:
            type: integer
          description: The ID of the pending project to decide upon.
          example: 7
      requestBody:
        required: true
        description: Decision payload.
        content:
          application/json:
            schema:
              $ref: './main.yaml#/components/schemas/projectDecision'
      responses:
        "204": # Use 204 No Content for successful action with no body
          description: No Content - Decision processed successfully.
        "400":
          description: Bad Request - Invalid input (e.g., missing decision).
        "401":
          description: Unauthorized.
          

  /admin/pending-accounts: # Path updated
    get:
      operationId: getPendingAccounts
      summary: Get accounts awaiting validation
      description: Retrieves a list of entrepreneur user accounts that are pending admin validation.
      tags:
        - Admin API
      security:
          - MyINPulse: [MyINPulse-admin]
      responses:
        "200":
          description: OK - List of pending accounts returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./main.yaml#/components/schemas/user-entrepreneur"
        "401":
          description: Unauthorized.

  /admin/accounts/validate/{userId}:
    post: # Changed to POST as it changes state
      operationId: validateUserAccount
      summary: Validate a pending user account
      description: Marks the user account specified by userId as validated/active.
      tags:
        - Admin API
      security:
          - MyINPulse: [MyINPulse-admin]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user account to validate.
          example: 102
      responses:
        "204":
          description: No Content - Account validated successfully.
        "400":
          description: Bad Request - Invalid user ID format.
          
        "401":
          description: Unauthorized.

  /admin/appointments/report/{appointmentId}:
    post:
      operationId: createAppointmentReport
      summary: Create a report for an appointment
      description: Creates and links a new report (e.g., meeting minutes) to the specified appointment using the provided content.
      tags:
        - Admin API
      security:
        - MyINPulse: [MyINPulse-admin]
      parameters:
        - in: path
          name: appointmentId
          required: true
          schema:
            type: integer
          description: ID of the appointment to add a report to.
          example: 303
      requestBody:
        required: true
        description: Report content. `idReport` will be ignored if sent.
        content:
          application/json:
            schema:
              $ref: "./main.yaml#/components/schemas/report"
      responses:
        "201":
          description: Created - Report created and linked successfully. Returns the created report.
          content:
             application/json:
                schema: { $ref: "./main.yaml#/components/schemas/report" }
        "400":
          description: Bad Request - Invalid input (e.g., missing content, invalid appointment ID format).
        "401":
          description: Unauthorized.
          
    put: # Changed to PUT for update/replacement
      operationId: updateAppointmentReport
      summary: Update an existing appointment report
      description: Updates the content of an existing report linked to the specified appointment. Replaces the entire report content.
      tags:
        - Admin API
      security:
        - MyINPulse: [MyINPulse-admin]
      parameters:
        - in: path
          name: appointmentId
          required: true
          schema:
            type: integer
          description: ID of the appointment whose report needs updating.
          example: 303
      requestBody:
        required: true
        description: New report content. `idReport` in the body should match the existing report's ID or will be ignored.
        content:
          application/json:
            schema:
              $ref: "./main.yaml#/components/schemas/report"
      responses:
        "200":
          description: OK - Report updated successfully. Returns the updated report.
          content:
             application/json:
                schema: { $ref: "./main.yaml#/components/schemas/report" }
        "400":
          description: Bad Request - Invalid input (e.g., missing content).
        "401":
          description: Unauthorized.


  /admin/projects/{projectId}:
    delete:
      operationId: removeProject
      summary: Remove a project
      description: Permanently removes the project specified by projectId and potentially related data (use with caution).
      tags:
        - Admin API
      security:
          - MyINPulse: [MyINPulse-admin]
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: integer
          description: The ID of the project to remove.
          example: 12
      responses:
        "204":
          description: No Content - Project removed successfully.
        "400":
          description: Bad Request - Invalid project ID format.
        "401":
          description: Unauthorized.
          


  /admin/make-admin/{userId}:
    post:
      operationId: grantAdminRights
      summary: Grant admin rights to a user
      tags:
        - Admin API
      security:
        - MyINPulse: [MyINPulse-admin]
      description: Elevates the specified user to also have administrator privileges. Assumes the user already exists.
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
          description: The ID of the user to grant admin rights.
          example: 103
      responses:
        "204": # Use 204 No Content
          description: No Content - Admin rights granted successfully.
        "400":
          description: Bad Request - Invalid user ID format or user is already an admin.     
        "401":
          description: Unauthorized.