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
  - name: Models
    description: Model management 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 /generate-token endpoint"
  /models:
    get:
      tags:
        - Models
      summary: Get models
      operationId: getModels
      description: Retrieve the list of available models. Note that some access tokens might not have access to all models.
      responses:
        '200':
          description: Successfully retrieved list of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
              example:
                models:
                  - name: "CoinToss-v1"
                    description: "A simple coin toss model"
                  - name: "LinearRegression-v1"
                    description: "A simple linear regression model"
                  - name: "GaussianMixture-v2"
                    description: "A simple Gaussian mixture model"
        '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 /generate-token endpoint"
  /models/{model_name}/info:
    get:
      tags:
        - Models
      summary: Get model information
      operationId: getModelInfo
      description: Retrieve detailed information about a specific model
      parameters:
        - name: model_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the model to retrieve information for (including version identifier if applicable, e.g. "CoinToss-v1")
      responses:
        '200':
          description: Successfully retrieved model information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelInfo'
        '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 /generate-token endpoint"
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Not Found"
                message: "The requested model could not be found"
                
  /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"
  /generate-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 /generate-token endpoint"
    ModelList:
      type: object
      required:
        - models
      properties:
        models:
          type: array
          description: List of available models
          items:
            $ref: '#/components/schemas/LightweightModelInfo'
    ModelInfo:
      type: object
      required:
        - info
        - config
      properties:
        info:
          $ref: '#/components/schemas/LightweightModelInfo'
          description: Basic model information
        config:
          type: object
          description: Model-specific configuration
          additionalProperties: true
    LightweightModelInfo:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: Name of the model (including version identifier, e.g. "CoinToss-v1")
        description:
          type: string
          description: Brief description of the model