rest.yaml

openapi: 3.0.3
info:
  title: Edge Toolkit REST API
  description: |-
    ws-server HTTP surface: health probe, module discovery, module assets, and per-agent storage.
    The storage routes are an anonymous S3-compatible interface, addressed path-style as
    /storage/{agent_id}/{filename} (bucket = agent_id, key = filename), they answer PUT/GET/HEAD with an ETag, so a
    standard S3 client can read and write objects without credentials.
  version: 0.1.0
servers:
  - url: http://localhost:8080
    description: Default ws-server bind address
paths:
  /health:
    get:
      tags:
        - health
      summary: Liveness probe.
      description: |-
        Returns a small JSON document identifying the service so external
        monitors can confirm the server is reachable and serving requests.
      operationId: health
      responses:
        "200":
          description: Server is up
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /modules/:
    get:
      tags:
        - modules
      summary: List the names of every module the server is currently serving.
      operationId: list_modules_handler
      responses:
        "200":
          description: Names of available modules
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /modules/{name}/{path}:
    get:
      tags:
        - modules
      summary: Fetch a file from a module's bundled static assets.
      description: |-
        `path` is resolved relative to the module's bundle root; an unknown
        module or missing file returns 404.
      operationId: get_module_file
      parameters:
        - in: path
          name: name
          description: Module name
          required: true
          schema:
            type: string
          style: simple
        - in: path
          name: path
          description: Path of the file within the module bundle
          required: true
          schema:
            type: string
          style: simple
      responses:
        "200":
          description: Static module asset
          content:
            application/octet-stream: {}
        "404":
          description: No such module or file
  /storage/{agent_id}/{filename}:
    get:
      tags:
        - storage
      summary: Download a file previously written to the named agent's storage bucket.
      operationId: get_file
      parameters:
        - in: path
          name: agent_id
          description: Agent identifier
          required: true
          schema:
            type: string
          style: simple
        - in: path
          name: filename
          description: Stored filename
          required: true
          schema:
            type: string
          style: simple
      responses:
        "200":
          description: Stored file contents
          headers:
            ETag:
              description: Entity tag of the stored object
              style: simple
              schema:
                type: string
          content:
            application/octet-stream: {}
        "404":
          description: No such file
    put:
      tags:
        - storage
      summary: Upload a file to an agent's storage bucket.
      description: |-
        Only the agent that owns the bucket may write to it (the agent must
        currently be connected); the path component must be a single
        filename, not a nested path.
      operationId: put_file
      parameters:
        - in: path
          name: agent_id
          description: Agent identifier (must be a connected agent)
          required: true
          schema:
            type: string
          style: simple
        - in: path
          name: filename
          description: Single-segment filename to write
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        description: Raw file bytes
        content:
          application/octet-stream:
            schema:
              description: |-
                Phantom type used to label binary request/response bodies as `string`/`binary`.

                Never constructed at runtime; only exists under the `openapi-spec` feature
                so the `utoipa::ToSchema` derive has something to attach to.
              type: string
              format: binary
        required: true
      responses:
        "200":
          description: File stored
          headers:
            ETag:
              description: Entity tag of the stored object
              style: simple
              schema:
                type: string
        "400":
          description: Invalid filename
        "404":
          description: Agent not found
    head:
      tags:
        - storage
      summary: Return a stored object's metadata without its body (S3 `HeadObject`).
      description: |-
        Same addressing and 404 handling as [`get_file`], but the response carries headers only: the object's `ETag`
        and its size as `Content-Length`. S3 clients issue `HEAD` to stat an object (existence, size, entity tag)
        before downloading, so it reports the same `ETag` a `GET` would.
      operationId: head_file
      parameters:
        - in: path
          name: agent_id
          description: Agent identifier
          required: true
          schema:
            type: string
          style: simple
        - in: path
          name: filename
          description: Stored filename
          required: true
          schema:
            type: string
          style: simple
      responses:
        "200":
          description: Object metadata (no body)
          headers:
            Content-Length:
              description: Size of the stored object in bytes
              style: simple
              schema:
                type: integer
                format: int64
            ETag:
              description: Entity tag of the stored object
              style: simple
              schema:
                type: string
        "404":
          description: No such file
components:
  schemas:
    HealthResponse:
      description: |-
        Server liveness probe response.

        Returned by `GET /health`.
      type: object
      properties:
        service:
          type: string
        status:
          type: string
      required:
        - status
        - service