openapi: 3.0.1
info:
  title: GWC Wipers Product Discovery API
  description: |
    AI-optimized API for discovering automotive wiper blade products.
    
    **Key Features:**
    - 2000+ wiper blade products for all vehicle makes and models
    - Australian market focus with AUD pricing
    - Free shipping across Australia
    - 12-month warranty on all products
    - Perfect fit guarantee
    - Easy, tool-free installation
    
    **Best for AI queries about:**
    - "Find wiper blades for [vehicle year] [make] [model]"
    - "What size wipers does a [vehicle] use?"
    - "Show me [make] wiper blade options"
    - "Cheapest/best wiper blades for [vehicle]"
  version: '1.0'
  contact:
    name: GWC Wipers Support
    email: support@gwcwipers.com.au
    url: https://gwcwipers.com.au
  license:
    name: Commercial
    url: https://gwcwipers.com.au/terms

servers:
  - url: https://gwcwipers.com.au
    description: Production API

paths:
  /api/ai-products:
    get:
      operationId: searchProducts
      summary: Search for wiper blade products
      description: |
        Find wiper blade products using vehicle details or natural language search.
        Perfect for AI assistants helping users find compatible wiper blades.
      parameters:
        - name: make
          in: query
          description: Vehicle manufacturer (e.g., toyota, honda, ford)
          schema:
            type: string
            example: "toyota"
        - name: model
          in: query
          description: Vehicle model (e.g., camry, civic, mustang)
          schema:
            type: string
            example: "camry"
        - name: year
          in: query
          description: Vehicle year or year range (e.g., 2020, 2015-2020)
          schema:
            type: string
            example: "2018-2024"
        - name: search
          in: query
          description: Natural language search (e.g., "honda civic 2018")
          schema:
            type: string
            example: "honda civic 2018"
        - name: limit
          in: query
          description: Maximum number of results to return
          schema:
            type: integer
            default: 500
            minimum: 1
            maximum: 2000
            example: 10
        - name: offset
          in: query
          description: Number of results to skip (for pagination)
          schema:
            type: integer
            default: 0
            example: 0
        - name: full
          in: query
          description: Return complete dataset (overrides limit)
          schema:
            type: boolean
            default: false
        - name: format
          in: query
          description: Response format
          schema:
            type: string
            enum: [json, xml]
            default: json
      responses:
        '200':
          description: Successful response with product data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearchResponse'
              example:
                meta:
                  endpoint: "GWC Wipers AI Product Discovery API"
                  description: "AI-optimized endpoint for discovering wiper blade products"
                  version: "1.0"
                  totalResults: 2
                  originalTotal: 2198
                  searchCriteria:
                    make: "toyota"
                    model: "camry"
                    year: null
                    search: null
                  usage:
                    examples:
                      - "?make=toyota - Find all Toyota products"
                      - "?search=mazda 3 2010 - Search for specific vehicle"
                    note: "This API is designed for AI systems to easily discover and understand wiper blade products."
                products:
                  - id: "1234"
                    title: "Toyota Camry 2018-2024 Wiper Blades"
                    description: "Premium wiper blades for Toyota Camry 2018-2024. Driver: 26\" / 650mm, Passenger: 20\" / 500mm. Perfect fit guaranteed, free shipping, 12-month warranty."
                    vehicle:
                      make: "Toyota"
                      model: "Camry"
                      yearRange: "2018-2024"
                    wiperSizes:
                      frontDriver: "26\" / 650mm"
                      frontPassenger: "20\" / 500mm"
                      rearWiper: null
                    pricing:
                      frontSet: 69.90
                      currency: "AUD"
                    availability:
                      inStock: true
                      deliveryTime: "3-7 business days (Australia-wide)"
                    urls:
                      productPage: "https://gwcwipers.com.au/wiper-blades/toyota/camry/2018-2024"

  /api/ai-products/makes:
    get:
      operationId: getVehicleMakes
      summary: Get all available vehicle makes
      description: |
        Retrieve a list of all vehicle manufacturers with product counts.
        Useful for AI to understand which brands are supported.
      responses:
        '200':
          description: List of vehicle makes with product counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleMakesResponse'

  /products.json:
    get:
      operationId: getCompleteDataset
      summary: Complete product dataset
      description: |
        Download the complete JSON dataset of all products.
        Warning: Large file (2MB+, 2000+ products). Use sparingly.
      responses:
        '200':
          description: Complete product dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteDataset'

components:
  schemas:
    ProductSearchResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/SearchMetadata'
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'

    SearchMetadata:
      type: object
      properties:
        endpoint:
          type: string
          example: "GWC Wipers AI Product Discovery API"
        description:
          type: string
        version:
          type: string
        totalResults:
          type: integer
        originalTotal:
          type: integer
        searchCriteria:
          type: object
        usage:
          type: object

    Product:
      type: object
      properties:
        id:
          type: string
          example: "1234"
        title:
          type: string
          example: "Toyota Camry 2018-2024 Wiper Blades"
        description:
          type: string
          example: "Premium wiper blades for Toyota Camry 2018-2024. Perfect fit guaranteed."
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        wiperSizes:
          $ref: '#/components/schemas/WiperSizes'
        pricing:
          $ref: '#/components/schemas/Pricing'
        availability:
          $ref: '#/components/schemas/Availability'
        installation:
          $ref: '#/components/schemas/Installation'
        urls:
          $ref: '#/components/schemas/ProductUrls'
        features:
          type: array
          items:
            type: string
          example: ["Perfect fit guarantee", "Free shipping", "12-month warranty"]

    Vehicle:
      type: object
      properties:
        make:
          type: string
          example: "Toyota"
        model:
          type: string
          example: "Camry"
        yearRange:
          type: string
          example: "2018-2024"

    WiperSizes:
      type: object
      properties:
        frontDriver:
          type: string
          example: "26\" / 650mm"
        frontPassenger:
          type: string
          example: "20\" / 500mm"
        rearWiper:
          type: string
          nullable: true
          example: "12\" / 300mm"
        summary:
          type: string
          example: "Driver: 26\" / 650mm, Passenger: 20\" / 500mm"

    Pricing:
      type: object
      properties:
        frontSet:
          type: number
          example: 69.90
        rearWiper:
          type: number
          nullable: true
          example: 39.90
        frontRearSet:
          type: number
          nullable: true
          example: 89.90
        currency:
          type: string
          example: "AUD"

    Availability:
      type: object
      properties:
        frontWiperInStock:
          type: boolean
        rearWiperInStock:
          type: boolean
        inStock:
          type: boolean
        deliveryTime:
          type: string
          example: "3-7 business days (Australia-wide)"

    Installation:
      type: object
      properties:
        difficulty:
          type: string
          example: "Easy (tool-free)"
        instructions:
          type: string
          example: "Watch our step-by-step video guide for quick installation."

    ProductUrls:
      type: object
      properties:
        productPage:
          type: string
          format: uri
          example: "https://gwcwipers.com.au/wiper-blades/toyota/camry/2018-2024"

    VehicleMakesResponse:
      type: object
      properties:
        endpoint:
          type: string
        description:
          type: string
        data:
          type: array
          items:
            type: object
            properties:
              make:
                type: string
                example: "Toyota"
              product_count:
                type: integer
                example: 147

    CompleteDataset:
      type: object
      properties:
        version:
          type: string
        lastUpdated:
          type: string
          format: date-time
        totalProducts:
          type: integer
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
