openapi: 3.0.3
info:
  title: StellaOps Graph Gateway (draft)
  version: 0.0.1-draft
servers:
  - url: https://gateway.local/api
paths:
  /graph/versions:
    get:
      summary: List graph schema versions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      type: string
  /graph/viewport:
    get:
      summary: Stream viewport tiles
      parameters:
        - name: bbox
          in: query
          required: true
          schema:
            type: string
        - name: zoom
          in: query
          required: true
          schema:
            type: integer
        - name: version
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Stream of tiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  tiles:
                    type: array
                    items:
                      type: object
  /graph/path:
    get:
      summary: Fetch path between nodes
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
        - name: to
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  edges:
                    type: array
                    items:
                      type: object
  /graph/diff:
    get:
      summary: Diff two snapshots
      parameters:
        - name: left
          in: query
          required: true
          schema:
            type: string
        - name: right
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /graph/export:
    get:
      summary: Export graph fragment
      parameters:
        - name: snapshot
          in: query
          required: true
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [graphml, jsonl]
      responses:
        '200':
          description: Streamed export
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer