openapi: 3.0.3
info:
  title: WHISKY:EDITION API
  description: Public API for whisky reviews, tasting notes, and metadata from WHISKY:EDITION.
  version: 1.2.1
servers:
  - url: https://thewhiskyedition.com
paths:
  /api/whisky-reviews:
    get:
      summary: List of whisky reviews
      parameters:
        - name: page
          in: query
          required: false
          description: Page of the result list
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: Number of reviews per page
          schema:
            type: integer
            default: 24
        - name: q
          in: query
          required: false
          description: Full-text search across titles, descriptions, and metadata
          schema:
            type: string
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: region
          in: query
          required: false
          schema:
            type: string
        - name: distillery
          in: query
          required: false
          schema:
            type: string
        - name: bottler
          in: query
          required: false
          schema:
            type: string
        - name: flavour
          in: query
          required: false
          schema:
            type: string
        - name: type
          in: query
          required: false
          schema:
            type: string
        - name: min_age
          in: query
          required: false
          schema:
            type: number
        - name: max_age
          in: query
          required: false
          schema:
            type: number
        - name: min_abv
          in: query
          required: false
          schema:
            type: number
        - name: max_abv
          in: query
          required: false
          schema:
            type: number
        - name: min_price
          in: query
          required: false
          schema:
            type: number
        - name: max_price
          in: query
          required: false
          schema:
            type: number
      responses:
        '200':
          description: List of published whisky reviews
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
  /api/whisky-reviews/{slug}:
    get:
      summary: Detailed information about a single whisky review
      parameters:
        - name: slug
          in: path
          required: true
          description: slug
          schema:
            type: string
      responses:
        '200':
          description: details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '404':
          description: Whisky review not found
components:
  schemas:
    List:
      type: object
      required: [ok, lang, count, total, page, per_page, items]
      properties:
        ok:
          type: boolean
        lang:
          type: string
          enum: [de, en]
        count:
          type: integer
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Summary'
    Summary:
      type: object
      required: [id, slug, lang, name, description, image, authors, metadata, rating, url]
      properties:
        id:
          type: integer
        slug:
          type: string
        lang:
          type: string
          enum: [de, en]
        name:
          type: string
        description:
          type: string
        image:
          type: object
          required: [url]
          properties:
            url:
              type: string
              format: uri
            alt:
              type: string
        authors:
          type: array
          items:
            type: string
            enum: [Marcel, Sascha]
        published_at:
          type: string
          format: date-time
          nullable: true
        metadata:
          $ref: '#/components/schemas/MetaData'
        rating:
          $ref: '#/components/schemas/Rating'
        url:
          type: string
        pdf:
          type: string
          description: URL path to the PDF export of this review
    Detail:
      allOf:
        - $ref: '#/components/schemas/Summary'
        - type: object
      required: [tasting_notes, conclusion]
      properties:
        tasting_notes:
          $ref: '#/components/schemas/Notes'
        conclusion:
          $ref: '#/components/schemas/Conclusion'
        faq:
          type: array
          items:
            type: object
            required: [question, answer]
            properties:
              question:
                type: string
              answer:
                type: string
    MetaData:
      type: object
      required: [type, country, distillery, abv]
      properties:
        type:
          type: string
        country:
          type: string
        region:
          type: string
        distillery:
          type: string
        bottler:
          type: string
        age:
          type: integer
        abv:
          type: number
        price_per_liter:
          type: number
        flavour:
          type: string
    Rating:
      type: object
      required: [marcel, sascha, value_for_money]
      properties:
        marcel:
          type: number
          minimum: 0
          maximum: 100
        sascha:
          type: number
          minimum: 0
          maximum: 100
        value_for_money:
          type: integer
          minimum: 1
          maximum: 5
    Notes:
      type: object
      required: [nose, palate, finish]
      properties:
        nose:
          type: string
        palate:
          type: string
        finish:
          type: string
    Conclusion:
      type: object
      required: [marcel, sascha]
      properties:
        marcel:
          type: string
        sascha:
          type: string
