openapi: 3.0.3
info:
  title: The Tea API
  description: |
    A free, read-only REST API for teas, ingredients, health benefits, and brewing data.
    No authentication required — every endpoint is a plain GET request that returns JSON.
    All responses are fully resolved: category, characteristics, health benefits, and
    ingredient composition are expanded inline so you never need multiple requests.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    url: https://theteaapi.com

servers:
  - url: https://theteaapi.com/api/v1
    description: Production (static CDN)

tags:
  - name: Teas
    description: Tea catalogue endpoints
  - name: Categories
    description: Tea category reference data
  - name: Tea Types
    description: True tea processing types (green, white, black, oolong, pu-erh)
  - name: Ingredients
    description: Ingredient reference data
  - name: Characteristics
    description: Flavour and aroma tags
  - name: Health Benefits
    description: Health benefit entries
  - name: Meta
    description: API metadata

paths:
  /teas.json:
    get:
      tags: [Teas]
      summary: List all teas
      description: Returns an array of all teas in the catalogue, fully expanded.
      operationId: listTeas
      responses:
        '200':
          description: Array of tea objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tea'

  /teas/{slug}.json:
    get:
      tags: [Teas]
      summary: Get tea by slug
      description: Returns a single tea by its URL-safe slug identifier.
      operationId: getTeaBySlug
      parameters:
        - name: slug
          in: path
          required: true
          description: URL-safe tea identifier (e.g. sencha, earl-grey)
          schema:
            type: string
            example: sencha
      responses:
        '200':
          description: A single tea object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tea'
        '404':
          description: Tea not found

  /categories.json:
    get:
      tags: [Categories]
      summary: List all categories
      description: Returns all tea categories with a tea_count field.
      operationId: listCategories
      responses:
        '200':
          description: Array of category objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryWithCount'

  /tea-types.json:
    get:
      tags: [Tea Types]
      summary: List all tea types
      description: Returns the five true-tea processing types with a tea_count field.
      operationId: listTeaTypes
      responses:
        '200':
          description: Array of tea type objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeaTypeWithCount'

  /ingredients.json:
    get:
      tags: [Ingredients]
      summary: List all ingredients
      description: Returns all ingredients used across the tea catalogue.
      operationId: listIngredients
      responses:
        '200':
          description: Array of ingredient objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Ingredient'

  /characteristics.json:
    get:
      tags: [Characteristics]
      summary: List all characteristics
      description: Returns all flavour and aroma characteristic tags.
      operationId: listCharacteristics
      responses:
        '200':
          description: Array of characteristic objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Characteristic'

  /health-benefits.json:
    get:
      tags: [Health Benefits]
      summary: List all health benefits
      description: Returns all catalogued health benefit entries referenced by teas.
      operationId: listHealthBenefits
      responses:
        '200':
          description: Array of health benefit objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HealthBenefit'

  /meta.json:
    get:
      tags: [Meta]
      summary: API metadata
      description: Returns API version, generation timestamp, total counts, and available endpoints.
      operationId: getMeta
      responses:
        '200':
          description: API metadata object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meta'

components:
  schemas:
    CaffeineLevel:
      type: string
      enum: [none, low, medium, high]
      description: Caffeine content level of the tea

    Category:
      type: object
      properties:
        id:          { type: integer, example: 1 }
        slug:        { type: string, example: true-tea }
        name:        { type: string, example: True Tea }
        description: { type: string }

    CategoryWithCount:
      allOf:
        - $ref: '#/components/schemas/Category'
        - type: object
          properties:
            tea_count: { type: integer, example: 14 }

    TeaType:
      type: object
      properties:
        id:          { type: integer, example: 1 }
        slug:        { type: string, example: green }
        name:        { type: string, example: Green Tea }
        description: { type: string }

    TeaTypeWithCount:
      allOf:
        - $ref: '#/components/schemas/TeaType'
        - type: object
          properties:
            tea_count: { type: integer, example: 5 }

    Ingredient:
      type: object
      properties:
        id:          { type: integer }
        name:        { type: string, example: Camellia sinensis leaves }
        description: { type: string }
        image_url:   { type: string, nullable: true, format: uri }

    Characteristic:
      type: object
      properties:
        id:   { type: integer }
        name: { type: string, example: Earthy }

    HealthBenefit:
      type: object
      properties:
        id:          { type: integer }
        name:        { type: string, example: Rich in antioxidants }
        description: { type: string }

    CompositionItem:
      type: object
      properties:
        amount:     { type: string, example: 2 tsp per 200ml }
        ingredient: { $ref: '#/components/schemas/Ingredient' }

    Tea:
      type: object
      properties:
        id:                    { type: integer }
        name:                  { type: string, example: Sencha }
        slug:                  { type: string, example: sencha }
        description:           { type: string }
        image_url:             { type: string, nullable: true, format: uri }
        origin:                { type: string, example: Shizuoka & Uji, Japan }
        caffeine_level:        { $ref: '#/components/schemas/CaffeineLevel' }
        temperature_celsius:   { type: integer, example: 75 }
        steeping_time_minutes: { type: number, example: 2 }
        brewing_instructions:  { type: string }
        category:              { $ref: '#/components/schemas/Category' }
        tea_type:
          nullable: true
          allOf: [{ $ref: '#/components/schemas/TeaType' }]
          description: Processing type for true teas — null for blends and tisanes
        base_type:
          nullable: true
          allOf: [{ $ref: '#/components/schemas/TeaType' }]
          description: True-tea base for blends — null for true teas and tisanes
        characteristics:
          type: array
          items: { $ref: '#/components/schemas/Characteristic' }
        health_benefits:
          type: array
          items: { $ref: '#/components/schemas/HealthBenefit' }
        composition:
          type: array
          items: { $ref: '#/components/schemas/CompositionItem' }

    Meta:
      type: object
      properties:
        version:          { type: string, example: 1.0.0 }
        generated_at:     { type: string, format: date-time }
        tea_count:        { type: integer }
        category_count:   { type: integer }
        ingredient_count: { type: integer }
        base_url:         { type: string, format: uri }
        endpoints:
          type: array
          items: { type: string }
