openapi: 3.0.3
info:
  title: TamoSoft Product API
  version: 1.0.0
  description: >
    OpenAPI interface to fetch product data from Magento. All GET endpoints are publicly accessible via api.tamos.com.
    The full YAML definition is available at https://api.tamos.com/openapi.yaml.

servers:
  - url: https://api.tamos.com

tags:
  - name: Products
  - name: Categories

externalDocs:
  description: OpenAPI YAML definition
  url: https://api.tamos.com/openapi.yaml

paths:
  /products:
    get:
      summary: Get all products
      tags:
        - Products
      description: Returns a list of all available products
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /products/upgrades:
    get:
      summary: Retrieve a list of available upgrades
      operationId: getUpgrades
      tags:
        - Products
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /products/recommended:
    get:
      summary: Retrieve a list of recommended products
      operationId: getRecommended
      tags:
        - Products
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /products/{sku}:
    get:
      summary: Get product details by SKU
      operationId: getProductBySku
      tags:
        - Products
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

  /categories:
    get:
      summary: Get a list of all categories
      operationId: getCategories
      tags:
        - Categories
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object

  /categories/{id}:
    get:
      summary: Get all products linked to a specific category
      operationId: getCategoryById
      tags:
        - Categories
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /search:
    get:
      summary: Search products by keyword
      operationId: searchProducts
      tags:
        - Products
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /status:
    get:
      summary: Check API health and version information
      operationId: getStatus
      tags:
        - Products
      responses:
        '200':
          description: API is operational
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  version:
                    type: string
                  timestamp:
                    type: string
                  cache:
                    type: object
                    properties:
                      products:
                        type: string
                      upgrades:
                        type: string
                      categories:
                        type: string
                      recommended:
                        type: string

components:
  schemas:
    Product:
      type: object
      properties:
        sku:
          type: string
        name:
          type: string
        price:
          type: number
          format: float
        url_key:
          type: string
        license:
          type: string
        type:
          type: string
        upgrade_group:
          type: string
        platforms:
          type: array
          items:
            type: string
        currency:
          type: string
        image:
          type: string
        short_description:
          type: string
        description:
          type: string