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'
  /system/file:
    post:
      summary: Upload a file
      description: Uploads a file to the system
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  description: Path where the file will be stored
                  example: "/path/to/file"
                content:
                  type: string
                  description: Base64 encoded content of the file
                  example: "SGVsbG8gV29ybGQh"
      responses:
        '200':
          description: File uploaded 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'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /system/restart:
    post:
      summary: Restart system
      description: Restarts the system
      responses:
        '200':
          description: System restarted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /system/shutdown:
    post:
      summary: Shutdown system
      description: Shuts down the system
      responses:
        '200':
          description: System shut down successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  
  /cluster/members:
    get:
      summary: Get cluster members
      description: Returns the list of nodes in the cluster
      responses:
        '200':
          description: Cluster members retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Name:
                      type: string
                      description: Node name
                      example: "rcond-agent"
                    Addr:
                      type: string
                      description: Node address
                      example: "192.168.1.100"
                    Port:
                      type: integer
                      description: Node port
                      example: 8080
                    Tags:
                      type: object
                      description: Node tags
                      example: {"role": "web", "env": "prod"}
                    Status:
                      type: integer
                      description: Node status
                      example: 1
                    ProtocolMin:
                      type: integer
                      description: Minimum protocol version
                      example: 1
                    ProtocolMax:
                      type: integer
                      description: Maximum protocol version
                      example: 1
                    ProtocolCur:
                      type: integer
                      description: Current protocol version
                      example: 1
                    DelegateMin:
                      type: integer
                      description: Minimum delegate version
                      example: 1
                    DelegateMax:
                      type: integer
                      description: Maximum delegate version
                      example: 1
                    DelegateCur:
                      type: integer
                      description: Current delegate version
                      example: 1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/join:
    post:
      summary: Join the cluster
      description: Join the cluster with the provided addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                join:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Successfully joined the cluster
          content:
            application/json:
              schema:
                type: object
                properties:
                  joined:
                    description: Number of nodes successfully joined
                    type: integer
                    example: 1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/leave:
    post:
      summary: Leave the cluster
      description: Leave the cluster
      responses:
        '200':
          description: Successfully left the cluster
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    description: Indicates if the node has left the cluster
                    type: boolean
                    example: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/event:
    post:
      summary: Send a cluster event
      description: Send a cluster event to all nodes in the cluster
      requestBody:
        description: Cluster event details
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Event name
                  type: string
                  example: "printHostname"
                payload:
                  description: Event payload
                  type: string
                  example: "blabla"
      responses:
        '200':
          description: Event sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Indicates if the event was sent successfully
                    type: string
                    example: "success"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'