openapi: 3.0.0
info:
  title: rcond API
  description: API for managing stuff on a Linux system
  version: 1.0.0

servers:
  - url: http://localhost:8080
    description: Local development server
  - url: http://rpi-test:8080
    description: Raspberry Pi test server
 
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Token
      description: API token for authentication
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: "some error message"

security:
  - ApiKeyAuth: []

paths:
  /health:
    get:
      summary: Health check endpoint
      description: Returns the health status of the service
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /network/sta:
    post:
      summary: Configure WiFi station
      description: Creates a WiFi station (client) configuration on the specified interface
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - interface
                - ssid
                - password
              properties:
                interface:
                  type: string
                  description: Network interface name
                  example: "wlan0"
                ssid:
                  type: string
                  description: WiFi network SSID
                  example: "MyNetworkSSID"
                password:
                  type: string
                  description: WiFi network password
                  example: "SuperSecretPassword"
                autoconnect:
                  type: boolean
                  description: Whether to automatically connect to the access point
                  example: true
      responses:
        '200':
          description: WiFi station configured successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    description: UUID of the created connection profile
                    example: "7d706027-727c-4d4c-a816-f0e1b99db8ab"
                  status:
                    type: string
                    description: Status of the operation
                    example: "success"
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /network/ap:
    post:
      summary: Configure WiFi access point
      description: Creates a WiFi access point configuration on the specified interface
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - interface
                - ssid
                - password
              properties:
                interface:
                  type: string
                  description: Network interface name
                  example: "wlan0"
                ssid:
                  type: string
                  description: WiFi network SSID
                  example: "MyNetworkSSID"
                password:
                  type: string
                  description: WiFi network password
                  example: "SuperSecretPassword"
                autoconnect:
                  type: boolean
                  description: Whether to automatically start the access point
                  example: true
      responses:
        '200':
          description: Access point configured successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    description: UUID of the created connection profile
                    example: "7d706027-727c-4d4c-a816-f0e1b99db8ab"
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /network/interface/{interface}:
    put:
      summary: Activate network connection
      description: Activates an existing network connection on the specified interface
      parameters:
        - name: interface
          in: path
          required: true
          schema:
            type: string
          description: Network interface name
          example: "wlan0"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - uuid
              properties:
                uuid:
                  type: string
                  description: UUID of the connection profile
                  example: "7d706027-727c-4d4c-a816-f0e1b99db8ab"
      responses:
        '200':
          description: Network interface brought up successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Deactivate network connection
      description: Deactivates the specified network connection
      parameters:
        - name: interface
          in: path
          required: true
          schema:
            type: string
          description: Network interface name
          example: "wlan0"
      responses:
        '200':
          description: Network interface brought down successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /network/connection/{uuid}:
    delete:
      summary: Remove stored connection profile
      description: Removes the stored NetworkManager connection profile
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
          description: UUID of the connection profile to remove
          example: "7d706027-727c-4d4c-a816-f0e1b99db8ab"
      responses:
        '200':
          description: Connection profile removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /hostname:
    get:
      summary: Get system hostname
      description: Returns the current system hostname
      responses:
        '200':
          description: Hostname retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  hostname:
                    type: string
                    description: Current hostname
                    example: "MyHostname"
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Set system hostname
      description: Sets a new system hostname
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - hostname
              properties:
                hostname:
                  type: string
                  description: New hostname to set
                  example: "MyHostname"
      responses:
        '200':
          description: Hostname set successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{user}/keys:
    post:
      summary: Add SSH authorized key
      description: Adds an SSH public key to a user's authorized_keys file
      parameters:
        - name: user
          in: path
          required: true
          schema:
            type: string
          description: Username to add key for
          example: "pi"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pubkey
              properties:
                pubkey:
                  type: string
                  description: SSH public key to add
                  example: "ssh-rsa AAAAB3NzaC1yc2E... user@host"
      responses:
        '200':
          description: Key added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  fingerprint:
                    type: string
                    description: Fingerprint of the added key
                    example: "SHA256:abcdef1234567890..."
        '400':
          description: Invalid request payload or SSH key format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{user}/keys/{fingerprint}:
    delete:
      summary: Remove SSH authorized key
      description: Removes an SSH public key from a user's authorized_keys file
      parameters:
        - name: user
          in: path
          required: true
          schema:
            type: string
          description: Username to remove key for
          example: "pi"
        - name: fingerprint
          in: path
          required: true
          schema:
            type: string
          description: URL-safe Base64 encoded fingerprint of the key to remove
          example: "U0hBMjU2OmFiY2RlZjEyMzQ1Njc4OTAuLi4="
      responses:
        '200':
          description: Key removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '400':
          description: Invalid request payload or fingerprint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'