openapi: 3.0.3
info:
  title: Shoehorn Metrics API
  description: |
    Real-time platform metrics for dashboard widgets. The current implementation
    returns a mix of live counts (from the catalog) and mock values for
    response-time, system, and integration metrics — responses include a
    `mock_data: true` flag wherever the values are synthetic. A future release
    will swap these for Prometheus-backed numbers.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /metrics/:
    get:
      summary: Get current platform metrics
      description: |
        Returns a snapshot of HTTP request counts, response-time samples,
        integration counts, and basic system stats. Used by the home and
        admin dashboards.
      tags: [Metrics]
      responses:
        '200':
          description: Metrics snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp: { type: string, format: date-time }
                  http_requests_total:
                    type: object
                    additionalProperties: { type: integer }
                    description: Request counts keyed by HTTP method.
                  response_times:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp: { type: string, format: date-time }
                        method: { type: string }
                        path: { type: string }
                        response_time_ms: { type: number }
                        status_code: { type: integer }
                  integrations_stats:
                    type: object
                    properties:
                      total: { type: integer }
                      active: { type: integer }
                      errors: { type: integer }
                      mock_data: { type: boolean }
                  system_stats:
                    type: object
                    properties:
                      database_connections: { type: integer }
                      cache_hits: { type: integer }
                      cache_misses: { type: integer }
                      memory_usage_bytes: { type: integer }
                      cpu_usage_percent: { type: number }
                      mock_data: { type: boolean }
                  mock_data:
                    type: boolean
                    description: True if any field in the response is synthetic.

  /metrics/timeseries:
    get:
      summary: Get a time-series for a named metric
      description: |
        Returns timestamps and values for a single metric over a window.
        Currently generates synthetic data; treat the shape as stable but the
        values as illustrative until the Prometheus backend lands.
      tags: [Metrics]
      parameters:
        - name: metric
          in: query
          required: true
          schema:
            type: string
            enum: [response_time, request_count, error_rate, cpu_usage, memory_usage]
        - name: range
          in: query
          schema:
            type: string
            enum: ["1h", "24h", "7d"]
            default: "24h"
      responses:
        '200':
          description: Time-series data
          content:
            application/json:
              schema:
                type: object
                properties:
                  metric: { type: string }
                  timeRange: { type: string }
                  timestamps:
                    type: array
                    items: { type: string, format: date-time }
                  values:
                    type: array
                    items: { type: number }
        '400':
          description: metric query parameter missing
