openapi: 3.0.3
info:
  title: PlainTracker API
  description: A set of endpoints to manage PlainTracker database
  version: 3.1.0
tags:
  - name: event
    description: Everything about your time clocks
servers:
  - url: /wp-json/plaintracker/v3
paths:
  /record:
    get:
      tags:
        - record
      description: Returns all time records.
      parameters:
        - name: limit
          in: query
          description: How many to return
          required: false
          schema:
            type: integer
            format: int64
            default: 10
        - name: offset
          in: query
          description: Listing offset
          required: false
          schema:
            type: integer
            format: int64
            default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Record'
        '400':
          description: Invalid status value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      tags:
        - event
      description: Adds a new time record.
      parameters:
        - name: X-WP-PlainTracker-Token
          in: header
          description: Authentication token
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Record'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Record'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        '400':
          description: Invalid input
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventError'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /record/{id}:
    get:
      tags:
        - record
      description: Returns a single time record.
      parameters:
        - name: id
          in: path
          description: ID of record to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        '404':
          description: Event not found
    put:
      tags:
        - record
      description: Updates a single time record.
      parameters:
        - name: id
          in: path
          description: ID of the record
          required: true
          schema:
            type: integer
            format: int64
        - name: X-WP-PlainTracker-Token
          in: header
          description: Authentication token
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Record'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Record'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        '404':
          description: Record not found
        '400':
          description: Invalid input
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordError'
components:
  schemas:
    Record:
      required:
        - clockIn
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        clockIn:
          # type: date-time
          # example: 2025-11-14 
          type: string
          pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$'
          description: A date and time in MySQL's default format.
          example: 2025-11-14 18:15:00
        clockInDescription:
          type: string
        clockOut:
          # type: date-time
          # example: 2025-11-14 
          type: string
          pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$'
          description: A date and time in MySQL's default format.
          example: 2025-11-14 18:15:00
        clockOutDescription:
          type: string
    EventError:
      type: object
      properties:
        clockIn:
          type: string
          example: Required field
        clockOut:
          type: string
          example: The clock out should be after the clock in
    Error:
      type: object
      properties:
        error:
          type: string
          example: An error message
      required:
        - error