`openapi.yaml`

873 lines
openapi: 3.0.3
info:
  title: Omega Watch Price History API
  description: |
    Comprehensive API for tracking and analyzing Omega watch prices, market trends, and investment opportunities.

    ## Features
    - Historical price tracking for 50+ Omega watches
    - Advanced analytics and predictions
    - Real-time WebSocket updates
    - Collection statistics and comparisons
    - Export capabilities (JSON/CSV)
    - Watchlist management

    ## Base URL
    - Production: `http://45.61.58.125:7600`
    - WebSocket: `ws://45.61.58.125:7600`

    ## Rate Limiting
    Currently no rate limiting is enforced. Fair usage is expected.

    ## Authentication
    No authentication required for public endpoints. Admin endpoints require authorization (future implementation).

  version: 2.0.0
  contact:
    name: API Support
    url: http://45.61.58.125:7600/api/docs
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://45.61.58.125:7600
    description: Production server
  - url: http://localhost:7600
    description: Local development

tags:
  - name: Health
    description: System health and monitoring
  - name: Watches
    description: Watch data and listings
  - name: Search
    description: Advanced search capabilities
  - name: Analytics
    description: Market analytics and predictions
  - name: Collections
    description: Watch collections and series
  - name: Watchlist
    description: User watchlist management
  - name: Export
    description: Data export functionality
  - name: Admin
    description: Administrative operations
  - name: WebSocket
    description: Real-time updates

paths:
  /api/health:
    get:
      tags:
        - Health
      summary: Health check endpoint
      description: Returns detailed system health metrics including uptime, memory usage, cache statistics, and database status
      operationId: getHealth
      responses:
        '200':
          description: System health information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                healthy:
                  value:
                    status: "healthy"
                    timestamp: "2024-11-17T10:30:00.000Z"
                    uptime: 3600.5
                    memory:
                      rss: 85678080
                      heapTotal: 54321664
                      heapUsed: 42123456
                      external: 1234567
                    cache:
                      keys: 15
                      size: 245678
                      oldestEntry: 1700223000000
                    database:
                      watches: 52
                      collections: 8
                    websocket:
                      connections: 3

  /api/watches:
    get:
      tags:
        - Watches
      summary: Get all watches
      description: Retrieve a paginated list of watches with optional filtering by series, year, and price range
      operationId: getWatches
      parameters:
        - name: series
          in: query
          description: Filter by watch series (e.g., Speedmaster, Seamaster)
          schema:
            type: string
            example: Speedmaster
        - name: minYear
          in: query
          description: Minimum year introduced
          schema:
            type: integer
            minimum: 1900
            example: 1960
        - name: maxYear
          in: query
          description: Maximum year introduced
          schema:
            type: integer
            maximum: 2024
            example: 2000
        - name: minPrice
          in: query
          description: Minimum current price (USD)
          schema:
            type: integer
            minimum: 0
            example: 5000
        - name: maxPrice
          in: query
          description: Maximum current price (USD)
          schema:
            type: integer
            example: 50000
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            example: 20
      responses:
        '200':
          description: Successful response with paginated watch list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchesListResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/search:
    get:
      tags:
        - Search
      summary: Advanced search
      description: Search watches by keyword with advanced filtering options
      operationId: searchWatches
      parameters:
        - name: q
          in: query
          required: true
          description: Search query string
          schema:
            type: string
            example: "moonwatch"
        - name: series
          in: query
          description: Filter by series
          schema:
            type: string
        - name: movement
          in: query
          description: Filter by movement type
          schema:
            type: string
            example: "automatic"
        - name: minPrice
          in: query
          schema:
            type: integer
        - name: maxPrice
          in: query
          schema:
            type: integer
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'

  /api/watches/trending:
    get:
      tags:
        - Watches
      summary: Get trending watches
      description: Returns the most viewed watches based on view count analytics
      operationId: getTrending
      parameters:
        - name: limit
          in: query
          description: Number of trending watches to return
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: List of trending watches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingResponse'

  /api/watches/{id}/history:
    get:
      tags:
        - Watches
      summary: Get watch price history
      description: Returns complete price history and specifications for a specific watch
      operationId: getWatchHistory
      parameters:
        - name: id
          in: path
          required: true
          description: Unique watch identifier
          schema:
            type: string
            example: "speedmaster-moonwatch-1969"
      responses:
        '200':
          description: Watch details and price history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchHistoryResponse'
        '404':
          description: Watch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/price-predictions/{id}:
    get:
      tags:
        - Analytics
      summary: Get price predictions
      description: Returns AI-generated price predictions for the next 3 years using linear regression analysis
      operationId: getPricePredictions
      parameters:
        - name: id
          in: path
          required: true
          description: Watch ID
          schema:
            type: string
      responses:
        '200':
          description: Price prediction data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricePredictionResponse'
        '404':
          description: Watch not found

  /api/collections:
    get:
      tags:
        - Collections
      summary: Get all collections
      description: Returns all watch collections with comprehensive statistics including average prices, appreciation rates, and watch counts
      operationId: getCollections
      responses:
        '200':
          description: Collections with statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsResponse'

  /api/statistics:
    get:
      tags:
        - Analytics
      summary: Get market statistics
      description: Returns comprehensive market statistics including total watches, average appreciation, top performers, and trend analysis
      operationId: getStatistics
      responses:
        '200':
          description: Market statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatisticsResponse'

  /api/compare:
    post:
      tags:
        - Watches
      summary: Compare watches
      description: Compare multiple watches side-by-side with price history and specifications
      operationId: compareWatches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - watchIds
              properties:
                watchIds:
                  type: array
                  items:
                    type: string
                  minItems: 2
                  maxItems: 10
                  example: ["speedmaster-moonwatch-1969", "seamaster-300-1957"]
      responses:
        '200':
          description: Comparison results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareResponse'
        '400':
          description: Invalid request

  /api/export/{format}:
    get:
      tags:
        - Export
      summary: Export data
      description: Export complete watch database in JSON or CSV format
      operationId: exportData
      parameters:
        - name: format
          in: path
          required: true
          description: Export format
          schema:
            type: string
            enum: [json, csv]
      responses:
        '200':
          description: Exported data file
          content:
            application/json:
              schema:
                type: object
            text/csv:
              schema:
                type: string

  /api/watchlist:
    post:
      tags:
        - Watchlist
      summary: Manage watchlist
      description: Add or remove watches from user watchlist
      operationId: manageWatchlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - watchId
                - action
              properties:
                userId:
                  type: string
                  example: "user123"
                watchId:
                  type: string
                  example: "speedmaster-moonwatch-1969"
                action:
                  type: string
                  enum: [add, remove]
                  example: "add"
      responses:
        '200':
          description: Updated watchlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResponse'

  /api/watchlist/{userId}:
    get:
      tags:
        - Watchlist
      summary: Get user watchlist
      description: Retrieve complete watchlist for a user
      operationId: getUserWatchlist
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User watchlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResponse'

  /api/analytics/predictions:
    get:
      tags:
        - Analytics
      summary: Get advanced predictions
      description: Returns ML-generated predictions from analytics engine
      operationId: getAnalyticsPredictions
      responses:
        '200':
          description: Prediction analytics
        '404':
          description: Analytics not generated yet

  /api/analytics/market:
    get:
      tags:
        - Analytics
      summary: Get market analysis
      description: Returns comprehensive market analysis including investment opportunities
      operationId: getMarketAnalysis
      responses:
        '200':
          description: Market analysis data

  /api/analytics/statistics:
    get:
      tags:
        - Analytics
      summary: Get statistical insights
      description: Returns advanced statistical insights and risk metrics
      operationId: getStatisticalInsights
      responses:
        '200':
          description: Statistical insights

  /api/analytics/investment-opportunities:
    get:
      tags:
        - Analytics
      summary: Get investment opportunities
      description: Returns top investment opportunities and value watches
      operationId: getInvestmentOpportunities
      responses:
        '200':
          description: Investment opportunities

  /api/analytics/risk-metrics:
    get:
      tags:
        - Analytics
      summary: Get risk metrics
      description: Returns risk-adjusted performance metrics for watches
      operationId: getRiskMetrics
      responses:
        '200':
          description: Risk metrics

  /api/admin/clear-cache:
    post:
      tags:
        - Admin
      summary: Clear cache
      description: Clears all cached data (requires admin access)
      operationId: clearCache
      responses:
        '200':
          description: Cache cleared successfully

  /api/admin/backup:
    get:
      tags:
        - Admin
      summary: Backup database
      description: Creates a timestamped backup of the database
      operationId: createBackup
      responses:
        '200':
          description: Backup created successfully

components:
  schemas:
    Watch:
      type: object
      required:
        - id
        - model
        - series
        - reference
        - yearIntroduced
        - priceHistory
      properties:
        id:
          type: string
          description: Unique identifier for the watch
          example: "speedmaster-moonwatch-1969"
        model:
          type: string
          description: Full model name
          example: "Speedmaster Professional Moonwatch ST 105.012"
        series:
          type: string
          description: Watch series/collection
          example: "Speedmaster"
        reference:
          type: string
          description: Reference number
          example: "ST 105.012"
        yearIntroduced:
          type: integer
          description: Year the watch was introduced
          example: 1963
        description:
          type: string
          description: Brief description
        priceHistory:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
        specifications:
          $ref: '#/components/schemas/Specifications'
        imageUrl:
          type: string
          format: uri
        detailedDescription:
          type: string

    PricePoint:
      type: object
      properties:
        year:
          type: integer
          example: 2020
        price:
          type: number
          description: Price in USD
          example: 125000
        condition:
          type: string
          enum: [new, vintage, excellent, good]
        source:
          type: string
          description: Source of price data

    Specifications:
      type: object
      properties:
        caseSize:
          type: string
          example: "42mm"
        caseMaterial:
          type: string
          example: "Stainless steel"
        movement:
          type: string
          example: "Calibre 321 (manual-winding)"
        waterResistance:
          type: string
          example: "50m"
        crystal:
          type: string
          example: "Hesalite"
        dialColor:
          type: string
        bezel:
          type: string
        lugWidth:
          type: string
        thickness:
          type: string
        powerReserve:
          type: string
        weight:
          type: string
        features:
          type: array
          items:
            type: string

    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: "healthy"
        timestamp:
          type: string
          format: date-time
        uptime:
          type: number
          description: Server uptime in seconds
        memory:
          type: object
          properties:
            rss:
              type: integer
            heapTotal:
              type: integer
            heapUsed:
              type: integer
            external:
              type: integer
        cache:
          type: object
          properties:
            keys:
              type: integer
            size:
              type: integer
            oldestEntry:
              type: integer
        database:
          type: object
          properties:
            watches:
              type: integer
            collections:
              type: integer
        websocket:
          type: object
          properties:
            connections:
              type: integer

    WatchesListResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total number of watches matching filters
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Items per page
        totalPages:
          type: integer
          description: Total number of pages
        watches:
          type: array
          items:
            $ref: '#/components/schemas/Watch'

    SearchResponse:
      type: object
      properties:
        query:
          type: string
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Watch'

    TrendingResponse:
      type: object
      properties:
        trending:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Watch'
              - type: object
                properties:
                  views:
                    type: integer
        totalViews:
          type: integer

    WatchHistoryResponse:
      type: object
      properties:
        watch:
          type: object
          properties:
            id:
              type: string
            model:
              type: string
            series:
              type: string
            reference:
              type: string
            yearIntroduced:
              type: integer
            specifications:
              $ref: '#/components/schemas/Specifications'
        priceHistory:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
        views:
          type: integer

    PricePredictionResponse:
      type: object
      properties:
        model:
          type: string
        currentPrice:
          type: number
        trend:
          type: string
          enum: [increasing, decreasing]
        averageAnnualChange:
          type: number
          description: Average annual change percentage
        predictions:
          type: array
          items:
            type: object
            properties:
              year:
                type: integer
              predictedPrice:
                type: number
              confidence:
                type: integer
                description: Confidence score (0-100)

    CollectionsResponse:
      type: object
      properties:
        collections:
          type: array
          items:
            type: object
            properties:
              series:
                type: string
              count:
                type: integer
              avgPrice:
                type: number
              avgAppreciation:
                type: number
              avgYearIntroduced:
                type: integer
              watches:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    model:
                      type: string
                    reference:
                      type: string
                    yearIntroduced:
                      type: integer
        totalCollections:
          type: integer

    StatisticsResponse:
      type: object
      properties:
        totalWatches:
          type: integer
        totalSeries:
          type: integer
        averageAppreciation:
          type: number
        topPerformers:
          type: array
          items:
            type: object
        lastUpdated:
          type: string
          format: date-time
        priceRanges:
          type: object
        movementTypes:
          type: object
        appreciationByDecade:
          type: object

    CompareResponse:
      type: object
      properties:
        watches:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Watch'
              - type: object
                properties:
                  currentPrice:
                    type: number
                  appreciation:
                    type: number
        count:
          type: integer

    WatchlistResponse:
      type: object
      properties:
        userId:
          type: string
        watchlist:
          type: array
          items:
            $ref: '#/components/schemas/Watch'
        count:
          type: integer

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        details:
          type: string
          description: Detailed error information

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for admin operations (future implementation)

security: []