openapi.yaml

openapi: 3.0.3
info:
  title: ML Model Registry API
  description: |
    API for managing machine learning models, their versions, and deployments.
    
    This API enables data scientists and ML engineers to:
    - Register and track ML models
    - Manage model versions
    - Update deployment status
    - View dashboard statistics
  version: 1.0.0
  contact:
    name: ML Model Registry Team
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8000/api/v1
    description: Local development server
  - url: https://ml-registry.example.com/api/v1
    description: Production server

tags:
  - name: models
    description: ML model management operations
  - name: versions
    description: Model version management
  - name: stats
    description: Dashboard statistics

paths:
  /models:
    get:
      tags:
        - models
      summary: List all models
      description: Retrieve a paginated list of all registered ML models with optional filtering
      operationId: listModels
      parameters:
        - name: skip
          in: query
          description: Number of records to skip for pagination
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          description: Maximum number of records to return
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: framework
          in: query
          description: Filter by ML framework
          required: false
          schema:
            type: string
            enum:
              - sklearn
              - tensorflow
              - pytorch
              - xgboost
              - lightgbm
              - onnx
              - other
        - name: status
          in: query
          description: Filter by deployment status
          required: false
          schema:
            $ref: '#/components/schemas/DeploymentStatus'
        - name: search
          in: query
          description: Search by model name or description
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response with list of models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelListResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

    post:
      tags:
        - models
      summary: Register a new model
      description: Register a new ML model in the registry
      operationId: createModel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelCreate'
      responses:
        '201':
          description: Model created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Model with this name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

  /models/{model_id}:
    get:
      tags:
        - models
      summary: Get model by ID
      description: Retrieve detailed information about a specific model
      operationId: getModel
      parameters:
        - $ref: '#/components/parameters/ModelId'
      responses:
        '200':
          description: Successful response with model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - models
      summary: Update model
      description: Update an existing model's information
      operationId: updateModel
      parameters:
        - $ref: '#/components/parameters/ModelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelUpdate'
      responses:
        '200':
          description: Model updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Model with this name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

    delete:
      tags:
        - models
      summary: Delete model
      description: Delete a model and all its versions
      operationId: deleteModel
      parameters:
        - $ref: '#/components/parameters/ModelId'
      responses:
        '204':
          description: Model deleted successfully
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /models/{model_id}/versions:
    get:
      tags:
        - versions
      summary: List model versions
      description: Get all versions of a specific model
      operationId: listModelVersions
      parameters:
        - $ref: '#/components/parameters/ModelId'
      responses:
        '200':
          description: Successful response with list of versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ModelVersion'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      tags:
        - versions
      summary: Create model version
      description: Add a new version to an existing model
      operationId: createModelVersion
      parameters:
        - $ref: '#/components/parameters/ModelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelVersionCreate'
      responses:
        '201':
          description: Version created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelVersion'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Version already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

  /models/{model_id}/deploy:
    post:
      tags:
        - models
      summary: Update deployment status
      description: Change the deployment status of a model
      operationId: deployModel
      parameters:
        - $ref: '#/components/parameters/ModelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentRequest'
      responses:
        '200':
          description: Deployment status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: Invalid status transition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /stats:
    get:
      tags:
        - stats
      summary: Get dashboard statistics
      description: Retrieve aggregated statistics for the dashboard
      operationId: getStats
      responses:
        '200':
          description: Successful response with statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardStats'

  /health:
    get:
      summary: Health check
      description: Check if the API is running
      operationId: healthCheck
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  version:
                    type: string
                    example: 1.0.0

components:
  parameters:
    ModelId:
      name: model_id
      in: path
      description: Unique identifier of the model
      required: true
      schema:
        type: string
        format: uuid

  schemas:
    DeploymentStatus:
      type: string
      enum:
        - development
        - staging
        - production
        - archived
      description: Current deployment status of the model

    Framework:
      type: string
      enum:
        - sklearn
        - tensorflow
        - pytorch
        - xgboost
        - lightgbm
        - onnx
        - other
      description: ML framework used to train the model

    Metrics:
      type: object
      description: Model performance metrics
      additionalProperties:
        type: number
      example:
        accuracy: 0.95
        f1_score: 0.93
        precision: 0.94
        recall: 0.92

    ModelBase:
      type: object
      properties:
        name:
          type: string
          description: Unique name for the model
          minLength: 1
          maxLength: 100
          example: customer-churn-predictor
        description:
          type: string
          description: Detailed description of the model
          maxLength: 1000
          example: Predicts customer churn probability based on usage patterns
        framework:
          $ref: '#/components/schemas/Framework'
        tags:
          type: array
          items:
            type: string
          description: Tags for categorization
          example:
            - classification
            - customer-analytics

    ModelCreate:
      allOf:
        - $ref: '#/components/schemas/ModelBase'
        - type: object
          required:
            - name
            - framework
          properties:
            version:
              type: string
              description: Initial version (defaults to 1.0.0)
              pattern: ^\d+\.\d+\.\d+$
              default: "1.0.0"
              example: "1.0.0"
            metrics:
              $ref: '#/components/schemas/Metrics'
            author:
              type: string
              description: Name of the model author
              example: Jane Smith

    ModelUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 1000
        tags:
          type: array
          items:
            type: string

    Model:
      allOf:
        - $ref: '#/components/schemas/ModelBase'
        - type: object
          required:
            - id
            - name
            - framework
            - status
            - created_at
            - updated_at
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier
              example: 123e4567-e89b-12d3-a456-426614174000
            status:
              $ref: '#/components/schemas/DeploymentStatus'
            current_version:
              type: string
              description: Current active version
              example: "1.2.0"
            metrics:
              $ref: '#/components/schemas/Metrics'
            author:
              type: string
              example: Jane Smith
            created_at:
              type: string
              format: date-time
              description: Timestamp when the model was created
            updated_at:
              type: string
              format: date-time
              description: Timestamp when the model was last updated

    ModelListResponse:
      type: object
      required:
        - items
        - total
        - skip
        - limit
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        total:
          type: integer
          description: Total number of models
          example: 42
        skip:
          type: integer
          description: Number of records skipped
          example: 0
        limit:
          type: integer
          description: Maximum records returned
          example: 20

    ModelVersionCreate:
      type: object
      required:
        - version
      properties:
        version:
          type: string
          description: Semantic version string
          pattern: ^\d+\.\d+\.\d+$
          example: "1.1.0"
        metrics:
          $ref: '#/components/schemas/Metrics'
        changelog:
          type: string
          description: Description of changes in this version
          example: Improved feature engineering, added regularization

    ModelVersion:
      type: object
      required:
        - id
        - model_id
        - version
        - created_at
      properties:
        id:
          type: string
          format: uuid
        model_id:
          type: string
          format: uuid
        version:
          type: string
          example: "1.1.0"
        metrics:
          $ref: '#/components/schemas/Metrics'
        changelog:
          type: string
        created_at:
          type: string
          format: date-time

    DeploymentRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/DeploymentStatus'

    DashboardStats:
      type: object
      required:
        - total_models
        - models_by_status
        - models_by_framework
        - recent_models
      properties:
        total_models:
          type: integer
          description: Total number of registered models
          example: 42
        models_by_status:
          type: object
          additionalProperties:
            type: integer
          example:
            development: 15
            staging: 10
            production: 12
            archived: 5
        models_by_framework:
          type: object
          additionalProperties:
            type: integer
          example:
            sklearn: 20
            pytorch: 12
            tensorflow: 8
            xgboost: 2
        recent_models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
          description: 5 most recently updated models

    Error:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Error message
          example: Model not found

    ValidationError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
              msg:
                type: string
              type:
                type: string