openapi: 3.0.3
info:
  title: DeBros Gateway API
  version: 1.0.0
  description: REST API over the DeBros Network client for storage, database, and pubsub.
servers:
  - url: http://localhost:8080
security:
  - ApiKeyAuth: []
  - BearerAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
    QueryRequest:
      type: object
      required: [sql]
      properties:
        sql:
          type: string
        args:
          type: array
          items: {}
    QueryResponse:
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            type: array
            items: {}
        count:
          type: integer
          format: int64
    TransactionRequest:
      type: object
      required: [statements]
      properties:
        statements:
          type: array
          items:
            type: string
    CreateTableRequest:
      type: object
      required: [schema]
      properties:
        schema:
          type: string
    DropTableRequest:
      type: object
      required: [table]
      properties:
        table:
          type: string
    TopicsResponse:
      type: object
      properties:
        topics:
          type: array
          items:
            type: string
paths:
  /v1/health:
    get:
      summary: Gateway health
      responses:
        '200': { description: OK }
  /v1/storage/put:
    post:
      summary: Store a value by key
      parameters:
        - in: query
          name: key
          schema: { type: string }
          required: true
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201': { description: Created }
        '400': { description: Bad Request, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
        '401': { description: Unauthorized }
        '500': { description: Error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
  /v1/storage/get:
    get:
      summary: Get a value by key
      parameters:
        - in: query
          name: key
          schema: { type: string }
          required: true
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404': { description: Not Found, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
  /v1/storage/exists:
    get:
      summary: Check key existence
      parameters:
        - in: query
          name: key
          schema: { type: string }
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
  /v1/storage/list:
    get:
      summary: List keys by prefix
      parameters:
        - in: query
          name: prefix
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: string
  /v1/storage/delete:
    post:
      summary: Delete a key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [key]
              properties:
                key: { type: string }
      responses:
        '200': { description: OK }
  /v1/db/create-table:
    post:
      summary: Create tables via SQL DDL
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateTableRequest' }
      responses:
        '201': { description: Created }
        '400': { description: Bad Request, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
        '500': { description: Error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
  /v1/db/drop-table:
    post:
      summary: Drop a table
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DropTableRequest' }
      responses:
        '200': { description: OK }
  /v1/db/query:
    post:
      summary: Execute a single SQL query
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QueryRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QueryResponse' }
        '400': { description: Bad Request, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
        '500': { description: Error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
  /v1/db/transaction:
    post:
      summary: Execute multiple SQL statements atomically
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TransactionRequest' }
      responses:
        '200': { description: OK }
        '400': { description: Bad Request, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
        '500': { description: Error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
  /v1/db/schema:
    get:
      summary: Get current database schema
      responses:
        '200': { description: OK }
  /v1/pubsub/publish:
    post:
      summary: Publish to a topic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic, data_base64]
              properties:
                topic: { type: string }
                data_base64: { type: string }
      responses:
        '200': { description: OK }
  /v1/pubsub/topics:
    get:
      summary: List topics in caller namespace
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TopicsResponse' }