openapi: 3.0.3
info:
  title: SPORE Registry API
  description: |
    RESTful API for managing firmware binaries in the SPORE embedded system.

    The SPORE registry provides storage and distribution of versioned firmware binaries
    with metadata management and hierarchical file organization.

    ## Features
    - **Firmware Upload**: Store firmware binaries with metadata
    - **Firmware Listing**: Query firmware by name, version, or labels
    - **Firmware Download**: Retrieve specific firmware versions
    - **Version Management**: Semantic versioning support with hierarchical storage

    ## Storage Structure
    Firmware binaries are stored hierarchically as:
    ```
    registry/{name}/{version}/firmware.bin
    ```

    Metadata is stored in SQLite database with labels for flexible querying.
  version: 1.0.0
  contact:
    name: SPORE Development Team
    url: https://git.dcentral.systems/iot/spore
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080
    description: Local SPORE registry server

paths:
  /firmware:
    post:
      summary: Upload firmware binary
      description: |
        Upload a firmware binary with metadata. The firmware is stored in the
        hierarchical file structure and metadata is saved to the database.
      operationId: uploadFirmware
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - metadata
                - firmware
              properties:
                metadata:
                  type: string
                  description: JSON metadata for the firmware
                  example: |
                    {
                      "name": "base",
                      "version": "1.0.0",
                      "labels": {
                        "app": "base",
                        "platform": "esp32"
                      }
                    }
                firmware:
                  type: string
                  format: binary
                  description: Firmware binary file
      responses:
        '201':
          description: Firmware uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  name:
                    type: string
                    example: "base"
                  version:
                    type: string
                    example: "1.0.0"
                  size:
                    type: integer
                    format: int64
                    example: 245760
        '400':
          description: Bad request - missing or invalid parameters
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string

    get:
      summary: List firmware records
      description: |
        Retrieve firmware records with optional filtering by name, version, or labels.
        Returns metadata for each firmware including download URLs.
      operationId: listFirmware
      parameters:
        - name: name
          in: query
          description: Filter by firmware name
          required: false
          schema:
            type: string
          example: "base"
        - name: version
          in: query
          description: Filter by firmware version
          required: false
          schema:
            type: string
          example: "1.0.0"
      responses:
        '200':
          description: List of firmware records
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: "base"
                    version:
                      type: string
                      example: "1.0.0"
                    size:
                      type: integer
                      format: int64
                      example: 245760
                    labels:
                      type: object
                      additionalProperties:
                        type: string
                      example:
                        app: "base"
                        platform: "esp32"
                    download_url:
                      type: string
                      example: "/firmware/base/1.0.0"
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string

  /firmware/{name}/{version}:
    get:
      summary: Download firmware binary
      description: |
        Download the firmware binary for the specified name and version.
        Returns the binary file directly.
      operationId: downloadFirmware
      parameters:
        - name: name
          in: path
          description: Firmware name
          required: true
          schema:
            type: string
          example: "base"
        - name: version
          in: path
          description: Firmware version (semantic versioning)
          required: true
          schema:
            type: string
          example: "1.0.0"
      responses:
        '200':
          description: Firmware binary file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Firmware not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string

    delete:
      summary: Delete firmware binary
      description: |
        Delete the firmware binary and metadata for the specified name and version.
        This action cannot be undone.
      operationId: deleteFirmware
      parameters:
        - name: name
          in: path
          description: Firmware name
          required: true
          schema:
            type: string
          example: "base"
        - name: version
          in: path
          description: Firmware version (semantic versioning)
          required: true
          schema:
            type: string
          example: "1.0.0"
      responses:
        '200':
          description: Firmware deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Firmware deleted successfully"
                  name:
                    type: string
                    example: "base"
                  version:
                    type: string
                    example: "1.0.0"
        '404':
          description: Firmware not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string

  /health:
    get:
      summary: Health check
      description: Simple health check endpoint
      operationId: healthCheck
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"

components:
  schemas:
    FirmwareMetadata:
      type: object
      required:
        - name
        - version
      properties:
        name:
          type: string
          description: Firmware name
          example: "base"
        version:
          type: string
          description: Firmware version (semantic versioning)
          example: "1.0.0"
        labels:
          type: object
          additionalProperties:
            type: string
          description: Key-value labels for categorizing firmware
          example:
            app: "base"
            platform: "esp32"

    FirmwareRecord:
      type: object
      properties:
        name:
          type: string
          example: "base"
        version:
          type: string
          example: "1.0.0"
        size:
          type: integer
          format: int64
          example: 245760
        labels:
          type: object
          additionalProperties:
            type: string
        download_url:
          type: string
          example: "/firmware/base/1.0.0"

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: integer
          description: HTTP status code