openapi: 3.0.2
info:
  title: RxInferServer OpenAPI specification
  description: API for RxInferServer.jl - A Julia server for RxInfer probabilistic programming framework
  version: 1.0.0
  contact:
    name: RxInferServer Team
    url: https://github.com/lazydynamics/RxInferServer
servers:
  - url: 'http://localhost:8000/v1'
    description: Local development server
tags:
  - name: Server
    description: Server management endpoints
  - name: Authentication
    description: Authentication related endpoints
# Global security - apply to all endpoints by default
security:
  - ApiKeyAuth: []
paths:
  /info:
    get:
      tags:
        - Server
      summary: Get server information
      operationId: getServerInfo
      description: Returns information about the server, such as the RxInfer version, Server version, Server edition, and Julia version
      responses:
        '200':
          description: Successfully retrieved server information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
              examples:
                known_versions:
                  value:
                    rxinfer_version: "4.2.0"
                    server_version: "1.0.0-DEV"
                    server_edition: "CommunityEdition"
                    julia_version: "1.11.3"
                    api_version: "v1"
                unknown_versions:
                  value:
                    rxinfer_version: "unknown"
                    server_version: "unknown" 
                    server_edition: "CommunityEdition"
                    julia_version: "1.11.3"
                    api_version: "v1"
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Unauthorized"
                message: "The request requires authentication, generate a token using the /token endpoint"
  /ping:
    get:
      tags:
        - Server
      summary: Health check endpoint
      operationId: pingServer
      description: Simple endpoint to check if the server is alive and running
      # This endpoint doesn't require authentication
      security: []
      responses:
        '200':
          description: Successfully pinged the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
              example:
                status: "ok"
  /token:
    post:
      tags:
        - Authentication
      summary: Generate authentication token
      operationId: generateToken
      description: Generates a new authentication token for accessing protected endpoints
      # This endpoint doesn't require authentication
      security: []
      responses:
        '200':
          description: Successfully generated authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Unable to generate token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Bad Request"
                message: "Unable to generate token due to internal error"
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Simple token authentication. Use the Authorization header with the Bearer scheme.
  schemas:
    ServerInfo:
      type: object
      required:
        - rxinfer_version
        - server_version
        - server_edition
        - julia_version
        - api_version
      properties:
        rxinfer_version:
          type: string
          description: The version of RxInfer that the server is using, returns unknown if the version is unknown or hidden
        server_version:
          type: string
          description: The version of the RxInferServer, returns unknown if the version is unknown or hidden
        server_edition:
          type: string
          description: The edition of the RxInferServer, as set in RXINFER_EDITION environment variable
        julia_version:
          type: string
          description: The version of Julia as presented in VERSION
        api_version:
          type: string
          description: The version of the API being used
          default: "v1"
    TokenResponse:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: The token to use in the Authorization header with the format "Bearer {token}"
    PingResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: Status of the server
          default: "ok"
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message explaining the failure
        message:
          type: string
          description: Additional message providing details about the failure
      example:
        error: "Unauthorized"
        message: "The request requires authentication, generate a token using the /token endpoint"