openapi: 3.0.3
info:
  title: Task Management API
  description: RESTful API for task management system implemented in 33 languages
  version: 1.0.0
  contact:
    name: David Christian Liedle
    email: david.liedle@gmail.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080/api/v1
    description: Local development server
  - url: https://api.example.com/v1
    description: Production server

paths:
  /tasks:
    get:
      summary: List all tasks
      operationId: listTasks
      tags:
        - Tasks
      parameters:
        - name: page_size
          in: query
          description: Maximum number of tasks to return
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: page_token
          in: query
          description: Page token for pagination
          schema:
            type: string
        - name: status
          in: query
          description: Filter by task status
          schema:
            $ref: '#/components/schemas/TaskStatus'
        - name: assigned_to
          in: query
          description: Filter by assigned user
          schema:
            type: string
        - name: tags
          in: query
          description: Filter by tags (comma-separated)
          schema:
            type: string
        - name: sort_order
          in: query
          description: Sort order for results
          schema:
            $ref: '#/components/schemas/SortOrder'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  next_page_token:
                    type: string
                  total_count:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    
    post:
      summary: Create a new task
      operationId: createTask
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
          headers:
            Location:
              description: URL of the created task
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  
  /tasks/{taskId}:
    get:
      summary: Get a task by ID
      operationId: getTask
      tags:
        - Tasks
      parameters:
        - name: taskId
          in: path
          required: true
          description: Task ID
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    
    put:
      summary: Update a task
      operationId: updateTask
      tags:
        - Tasks
      parameters:
        - name: taskId
          in: path
          required: true
          description: Task ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
    
    delete:
      summary: Delete a task
      operationId: deleteTask
      tags:
        - Tasks
      parameters:
        - name: taskId
          in: path
          required: true
          description: Task ID
          schema:
            type: string
      responses:
        '204':
          description: Task deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  
  /tasks/{taskId}/status:
    patch:
      summary: Update task status
      operationId: updateTaskStatus
      tags:
        - Tasks
      parameters:
        - name: taskId
          in: path
          required: true
          description: Task ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  $ref: '#/components/schemas/TaskStatus'
      responses:
        '200':
          description: Status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  schemas:
    Task:
      type: object
      required:
        - id
        - title
        - status
        - priority
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the task
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Title of the task
        description:
          type: string
          maxLength: 2000
          description: Detailed description of the task
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          $ref: '#/components/schemas/TaskPriority'
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the task
        created_by:
          type: string
          description: User who created the task
        assigned_to:
          type: string
          description: User currently assigned to the task
        created_at:
          type: string
          format: date-time
          description: When the task was created
        updated_at:
          type: string
          format: date-time
          description: When the task was last updated
        due_date:
          type: string
          format: date-time
          description: When the task is due
        completed_at:
          type: string
          format: date-time
          description: When the task was completed
    
    TaskStatus:
      type: string
      enum:
        - pending
        - in_progress
        - completed
        - cancelled
        - on_hold
      description: Current status of the task
    
    TaskPriority:
      type: string
      enum:
        - low
        - medium
        - high
        - critical
      description: Priority level of the task
    
    SortOrder:
      type: string
      enum:
        - created_at_asc
        - created_at_desc
        - due_date_asc
        - due_date_desc
        - priority_asc
        - priority_desc
      description: Sort order for task listing
    
    CreateTaskRequest:
      type: object
      required:
        - title
        - priority
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        priority:
          $ref: '#/components/schemas/TaskPriority'
        tags:
          type: array
          items:
            type: string
        assigned_to:
          type: string
        due_date:
          type: string
          format: date-time
    
    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          $ref: '#/components/schemas/TaskPriority'
        tags:
          type: array
          items:
            type: string
        assigned_to:
          type: string
        due_date:
          type: string
          format: date-time
    
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
  
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - BearerAuth: []
  - ApiKeyAuth: []

tags:
  - name: Tasks
    description: Task management operations