openapi: 3.0.3
info:
  title: SwitchMall Public Product Statistics API
  version: 1.0.0
  description: Read-only public SwitchMall product view and reaction counts.
  contact:
    name: SwitchMall Developer Resources
    url: https://switchmall.ai/developers
externalDocs:
  description: SwitchMall Public API documentation
  url: https://switchmall.ai/developers/api
servers:
  - url: https://switchmall.ai
security: []
tags:
  - name: SwitchMall Products
    description: Read-only public information associated with SwitchMall product IDs.
paths:
  /api/public/v1/products/{productId}/stats:
    get:
      operationId: getSwitchMallProductStats
      summary: Get SwitchMall product statistics
      description: Returns current view, like and dislike counts for a SwitchMall product ID. No authentication is required.
      security: []
      tags:
        - SwitchMall Products
      parameters:
        - name: productId
          in: path
          required: true
          description: Positive SwitchMall product ID.
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 9007199254740991
          example: 1
      responses:
        "200":
          description: Current SwitchMall product statistics.
          headers:
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductStats"
              example:
                productId: 1
                viewsCount: 0
                likesCount: 0
                dislikesCount: 0
        "400":
          $ref: "#/components/responses/BadRequest"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/ServerError"
components:
  schemas:
    ProductStats:
      type: object
      required:
        - productId
        - viewsCount
        - likesCount
        - dislikesCount
      properties:
        productId:
          type: integer
          format: int64
          minimum: 1
          maximum: 9007199254740991
          description: SwitchMall product ID supplied in the request path.
        viewsCount:
          type: integer
          minimum: 0
          description: Recorded product view events.
        likesCount:
          type: integer
          minimum: 0
          description: Current positive reactions.
        dislikesCount:
          type: integer
          minimum: 0
          description: Current negative reactions.
      additionalProperties: false
    Error:
      type: object
      required:
        - error
        - code
        - message
        - resolution
      properties:
        error:
          type: string
          description: Backward-compatible human-readable error message.
        code:
          type: string
          description: Stable machine-readable error code.
          enum:
            - INVALID_PRODUCT_ID
            - METHOD_NOT_ALLOWED
            - RATE_LIMIT_EXCEEDED
            - INTERNAL_ERROR
            - API_ROUTE_NOT_FOUND
        message:
          type: string
          description: Human-readable explanation of the failure.
        resolution:
          type: string
          description: Concrete guidance for correcting or retrying the request.
      additionalProperties: false
  responses:
    BadRequest:
      description: Invalid SwitchMall product ID.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Product ID must be a positive integer
            code: INVALID_PRODUCT_ID
            message: Product ID must be a positive integer
            resolution: Provide a positive integer SwitchMall product ID in the URL path.
    MethodNotAllowed:
      description: Unsupported HTTP method.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Method not allowed
            code: METHOD_NOT_ALLOWED
            message: Method not allowed
            resolution: Call this endpoint with GET or OPTIONS.
    TooManyRequests:
      description: Public rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until another request may be attempted.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Rate limit exceeded
            code: RATE_LIMIT_EXCEEDED
            message: Rate limit exceeded
            resolution: Wait for the Retry-After interval before retrying.
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: Internal server error
            code: INTERNAL_ERROR
            message: Internal server error
            resolution: Retry later or use the SwitchMall contact page if the problem continues.