api-spec.yaml

openapi: 3.0.0
info:
  title: AI4Devs Candidate API
  version: 1.0.0
  description: API for managing candidate data in the AI4Devs recruitment system.
paths:
  /candidates:
    post:
      summary: Add a new candidate
      description: Adds a new candidate to the system and returns the created candidate data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: First name of the candidate
                  minLength: 2
                  maxLength: 50
                  pattern: '^[a-zA-ZñÑáéíóúÁÉÍÓÚ ]+$'
                lastName:
                  type: string
                  description: Last name of the candidate
                  minLength: 2
                  maxLength: 50
                  pattern: '^[a-zA-ZñÑáéíóúÁÉÍÓÚ ]+$'
                email:
                  type: string
                  description: Email address of the candidate
                  pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
                phone:
                  type: string
                  description: Phone number of the candidate
                  pattern: '^\+?\d{1,3}?[- .]?\(?(?:\d{2,3})\)?[- .]?\d\d\d[- .]?\d\d\d\d$'
                address:
                  type: string
                  description: Address of the candidate
                  maxLength: 100
                educations:
                  type: array
                  description: Education history of the candidate
                  items:
                    type: object
                    properties:
                      institution:
                        type: string
                        description: Institution name
                        maxLength: 100
                      title:
                        type: string
                        description: Degree or title obtained
                        maxLength: 100
                      startDate:
                        type: string
                        description: Start date of the education
                        pattern: '^\d{4}-\d{2}-\d{2}$'
                      endDate:
                        type: string
                        description: End date of the education
                        pattern: '^\d{4}-\d{2}-\d{2}$'
                workExperiences:
                  type: array
                  description: Work experience of the candidate
                  items:
                    type: object
                    properties:
                      company:
                        type: string
                        description: Company name
                        maxLength: 100
                      position:
                        type: string
                        description: Position held
                        maxLength: 100
                      description:
                        type: string
                        description: Description of the job responsibilities
                        maxLength: 200
                      startDate:
                        type: string
                        description: Start date of the job
                        pattern: '^\d{4}-\d{2}-\d{2}$'
                      endDate:
                        type: string
                        description: End date of the job
                        pattern: '^\d{4}-\d{2}-\d{2}$'
                cv:
                  type: object
                  description: CV file information
                  properties:
                    filePath:
                      type: string
                      description: Path to the CV file
                    fileType:
                      type: string
                      description: Type of the CV file
      responses:
        '201':
          description: Candidate created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the candidate
                  firstName:
                    type: string
                  lastName:
                    type: string
                  email:
                    type: string
                  phone:
                    type: string
                  address:
                    type: string
                  educations:
                    type: array
                    items:
                      type: object
                      properties:
                        institution:
                          type: string
                        title:
                          type: string
                        startDate:
                          type: string
                        endDate:
                          type: string
                  workExperiences:
                    type: array
                    items:
                      type: object
                      properties:
                        company:
                          type: string
                        position:
                          type: string
                        description:
                          type: string
                        startDate:
                          type: string
                        endDate:
                          type: string
                  cv:
                    type: object
        '400':
          description: Bad request (invalid input data)
        '500':
          description: Internal server error
  /upload:
    post:
      summary: Upload a file
      description: Uploads a file to the server. Only PDF and DOCX files are allowed.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: File to be uploaded
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  filePath:
                    type: string
                    description: Path where the file is stored
                  fileType:
                    type: string
                    description: MIME type of the uploaded file
        '400':
          description: Invalid file type, only PDF and DOCX are allowed
        '500':
          description: Error during the file upload process
  /position/{id}/candidates:
    get:
      summary: Get candidates by position
      description: Retrieves all candidates for a specific position.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: ID of the position
      responses:
        '200':
          description: List of candidates
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    fullName:
                      type: string
                    currentInterviewStep:
                      type: string
                    averageScore:
                      type: number
        '404':
          description: Position not found
        '500':
          description: Internal server error
  /candidates/{id}:
    put:
      summary: Update candidate stage
      description: Updates the interview stage of a specific candidate.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: ID of the candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicationId:
                  type: integer
                  description: ID of the application
                currentInterviewStep:
                  type: integer
                  description: Current interview step
      responses:
        '200':
          description: Candidate stage updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      positionId:
                        type: integer
                      candidateId:
                        type: integer
                      applicationDate:
                        type: string
                        format: date-time
                      currentInterviewStep:
                        type: integer
                      notes:
                        type: string
                        nullable: true
                      interviews:
                        type: array
                        items:
                          type: object
                          properties:
                            interviewDate:
                              type: string
                              format: date-time
                            interviewStep:
                              type: string
                            score:
                              type: number
                              nullable: true
        '400':
          description: Invalid input data
        '404':
          description: Candidate or application not found
        '500':
          description: Internal server error