cocktails.yml

openapi: 3.0.3
info:
  title: Cocktail and ingredient API
  version: 0.0.1

servers:
  - url: http://localhost:8080/
    description: Local development server

tags:
  - name: types
    description: Information about ingredient types
  - name: ingredients
    description: Information about ingredients
  - name: cocktails
    description: Information about cocktails
paths:
  /types:
    get:
      summary: Get a list of ingredient types
      description: Fetches a paginated list of ingredient types. Maximum sizes may be limited
      operationId: listTypes
      tags:
        - types
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedTypes"
    post:
      summary: Create a new type
      description: Create a new ingredient type in the database
      operationId: createType
      tags:
        - types
      requestBody:
        description: A new ingredient type to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIngredientType"
      responses:
        201:
          description: Type created
          headers:
            Location:
              schema:
                type: string
                format: uri
                example: https://example.com/types/e49350c8-942b-4c38-b1b7-98f7d4547483
              description: Location of the created type
              required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngredientType"
        409:
          description: Type with name already exists
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /types/count:
    get:
      summary: Count ingredient types
      description: The amount of ingredient types currently stored
      operationId: countTypes
      tags:
        - types
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: integer
                format: int64
                example: 1337
  /types/{id}:
    parameters:
      - $ref: "#/components/parameters/locatorId"
    get:
      summary: Get a single type
      description: A single ingredient type
      operationId: getType
      tags:
        - types
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngredientType"
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
    put:
      summary: Update a type
      description: Update a single ingredient type
      operationId: updateType
      tags:
        - types
      requestBody:
        description: A new ingredient type to be created
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIngredientType"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngredientType"
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        409:
          description: Type with name already exists
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
    delete:
      summary: Delete a type
      description: Delete a type of ingredient. Does not work if that type is still used by an ingredient
      operationId: deleteType
      tags:
        - types
      responses:
        204:
          description: Success
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        422:
          description: Type cannot be deleted because it is still in use
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /types/{id}/ingredients:
    parameters:
      - $ref: "#/components/parameters/locatorId"
    get:
      summary: Get a list of ingredients that have this type
      description: Fetches a paginated list of ingredients. Maximum sizes may be limited
      operationId: listIngredientsByType
      tags:
        - ingredients
        - types
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedIngredients"
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /ingredients:
    get:
      summary: Get a list of ingredients
      description: Fetches a paginated list of ingredients. Maximum sizes may be limited
      operationId: listIngredients
      tags:
        - ingredients
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedIngredients"
    post:
      summary: Create ingredient
      description: Creates a new ingredient in the database
      operationId: createIngredient
      tags:
        - ingredients
      requestBody:
        description: Ingredient data to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIngredient"
      responses:
        201:
          description: Ingredient created
          headers:
            Location:
              schema:
                type: string
                format: uri
                example: https://example.com/ingredients/e49350c8-942b-4c38-b1b7-98f7d4547483
              description: Location of the created ingredient
              required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ingredient"
        422:
          description: Ingredient type does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /ingredients/count:
    get:
      summary: Count ingredients
      description: The amount of ingredients currently stored
      operationId: countIngredients
      tags:
        - ingredients
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: integer
                format: int64
                example: 1337
  /ingredients/{id}:
    parameters:
      - $ref: "#/components/parameters/locatorId"
    get:
      summary: Find an ingredient
      description: A single ingredient
      operationId: getIngredient
      tags:
        - ingredients
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ingredient"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
    delete:
      summary: Delete an ingredient
      description: |
        Delete an ingredient from the list of ingredients.
        Does not work if the ingredient is referenced by a cocktail
      operationId: deleteIngredient
      tags:
        - ingredients
      responses:
        204:
          description: Success
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        422:
          description: Ingredient cannot be deleted because it is still in use
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
    put:
      summary: Update an ingredient
      description: Update an ingredient
      operationId: updateIngredient
      tags:
        - ingredients
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ingredient"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /ingredients/{id}/cocktails:
    parameters:
      - $ref: "#/components/parameters/locatorId"
    get:
      summary: Get a list of cocktails that use this ingredient
      description: Fetches a paginated list of cocktails. Maximum sizes may be limited
      operationId: listCocktailsByIngredient
      tags:
        - cocktails
        - ingredients
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedCocktails"
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /cocktails:
    get:
      summary: Get a list of cocktails
      description: Fetches a paginated list of cocktails. Maximum sizes may be limited
      operationId: listCocktails
      tags:
        - cocktails
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/pageSize"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedCocktails"
    post:
      summary: Create a new cocktail
      description: Create a new cocktail in the database
      operationId: createCocktail
      tags:
        - cocktails
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCocktail"
      responses:
        201:
          description: Cocktail created
          headers:
            Location:
              schema:
                type: string
                format: uri
                example: https://example.com/cocktails/e49350c8-942b-4c38-b1b7-98f7d4547483
              description: Location of the created cocktail
              required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Cocktail"
        422:
          description: Ingredient does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /cocktails/{id}:
    parameters:
      - $ref: "#/components/parameters/locatorId"
    get:
      summary: Get a single cocktail
      description: Fetch a complete representation of a given cocktail
      operationId: getCocktail
      tags:
        - cocktails
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Cocktail"
        404:
          description: Not found
    put:
      summary: Update a cocktail
      description: Update a cocktail
      operationId: updateCocktail
      tags:
        - cocktails
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCocktail"
      responses:
        200:
          description: Cocktail updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Cocktail"
        422:
          description: Ingredient does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
    delete:
      summary: Delete a cocktail
      description: Delete a cocktail
      operationId: deleteCocktail
      tags:
        - cocktails
      responses:
        204:
          description: Success
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /cocktails/count:
    get:
      summary: Count cocktails
      description: The amount of cocktails currently stored
      operationId: countCocktails
      tags:
        - cocktails
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: integer
                format: int64
                example: 1337
components:
  schemas:
    IngredientType:
      description: Describes a type of ingredient
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          example: e49350c8-942b-4c38-b1b7-98f7d4547483
        name:
          type: string
          example: Fruit juice
    CreateIngredientType:
      description: Describes a new type of ingredient for creation or update
      required:
        - name
      properties:
        name:
          type: string
          example: Fruit juice
    Ingredient:
      description: Describes an ingredient
      required:
        - id
        - type
        - name
      properties:
        id:
          type: string
          format: uuid
          example: e49350c8-942b-4c38-b1b7-98f7d4547483
        type:
          $ref: "#/components/schemas/IngredientType"
        name:
          type: string
          example: Lime juice
        description:
          type: string
          example: A very tart citrus juice
    CreateIngredient:
      description: A new ingredient
      required:
        - type
        - name
      properties:
        type:
          type: string
          format: uuid
          example: e49350c8-942b-4c38-b1b7-98f7d4547483
          description: UUID of the type this ingredient has
        name:
          type: string
          description: Lime juice
        description:
          type: string
          description: A very tart citrus juice
    Cocktail:
      description: Describes a cocktail
      required:
        - id
        - name
        - ingredients
        - instructions
      properties:
        id:
          type: string
          format: uuid
          example: e49350c8-942b-4c38-b1b7-98f7d4547483
        name:
          type: string
          example: Daiquiri
        description:
          type: string
          example: A sour cocktail made with rum
        ingredients:
          type: array
          items:
            $ref: "#/components/schemas/CocktailIngredient"
          minLength: 1
        instructions:
          type: array
          items:
            $ref: "#/components/schemas/CocktailInstruction"
          minLength: 1
    CocktailListEntry:
      description: Describes an entry in a list of cocktails
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          example: e49350c8-942b-4c38-b1b7-98f7d4547483
        name:
          type: string
          example: Daiquiri
        description:
          type: string
          example: A sour cocktail made with rum
    CocktailIngredient:
      description: An ingredient as used in a cocktail
      allOf:
        - $ref: "#/components/schemas/Ingredient"
      properties:
        amount:
          type: number
          format: double
          exclusiveMinimum: true
          minimum: 0
          description: An optional amount of the given ingredient
        unit:
          $ref: "#/components/schemas/Unit"
        optional:
          type: boolean
          description: Whether or not this ingredient is optional in the cocktail
          default: false
        garnish:
          type: boolean
          description: Whether or not this ingredient is a garnish. Garnishes are always optional
          default: false
    CreateCocktailIngredient:
      description: An ingredient for creating a cocktail
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          example: e49350c8-942b-4c38-b1b7-98f7d4547483
          description: ID of the ingredient
        amount:
          type: number
          format: double
          exclusiveMinimum: true
          minimum: 0
          description: An optional amount of the given ingredient
        unit:
          $ref: "#/components/schemas/Unit"
        optional:
          type: boolean
          description: Whether or not this ingredient is optional in the cocktail
          default: false
        garnish:
          type: boolean
          description: Whether or not this ingredient is a garnish. Garnishes are always optional
          default: false
    CocktailInstruction:
      description: A step in the preparation of a cocktail
      required:
        - text
      properties:
        text:
          type: string
          description: The preparation instruction
          example: Add ice to the shaker, seal, and shake vigorously
    CreateCocktail:
      description: A new cocktail
      required:
        - name
        - ingredients
        - instructions
      properties:
        name:
          type: string
          example: Daiquiri
        description:
          type: string
          example: A sour cocktail made with rum
        ingredients:
          description: The ingredients needed for this cocktail
          type: array
          items:
            $ref: "#/components/schemas/CreateCocktailIngredient"
          minItems: 1
        instructions:
          description: The steps of making the cocktail, in order
          type: array
          items:
            $ref: "#/components/schemas/CocktailInstruction"
          minItems: 1
    Problem:
      type: object
      additionalProperties: true
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: 'about:blank'
          example: 'https://zalando.github.io/problem/constraint-violation'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
    Unit:
      description: A unit for measuring ingredients
      type: string
      enum:
        - GRAMS
        - MILLILITERS
        - BARSPOONS
    PagedResult:
      required:
        - total
        - lastPage
      properties:
        total:
          description: The total amount of entries for this result
          type: integer
          format: int64
          example: 1337
        lastPage:
          description: The last possible page for this result
          type: integer
          format: int64
          example: 123
    PagedCocktails:
      allOf:
        - $ref: "#/components/schemas/PagedResult"
      required:
        - cocktails
      properties:
        cocktails:
          type: array
          items:
            $ref: "#/components/schemas/CocktailListEntry"
    PagedIngredients:
      allOf:
        - $ref: "#/components/schemas/PagedResult"
      required:
        - ingredients
      properties:
        ingredients:
          type: array
          items:
            $ref: "#/components/schemas/Ingredient"
    PagedTypes:
      allOf:
        - $ref: "#/components/schemas/PagedResult"
      required:
        - types
      properties:
        types:
          type: array
          items:
            $ref: "#/components/schemas/IngredientType"
  parameters:
    page:
      in: query
      name: page
      description: What page to fetch
      required: false
      schema:
        type: integer
        minimum: 1
        example: 1
        default: 1
    pageSize:
      in: query
      name: pageSize
      description: Size of the page to fetch
      required: false
      schema:
        type: integer
        minimum: 1
        example: 20
        default: 20
    locatorId:
      in: path
      name: id
      description: A uuid for fetching a resource
      required: true
      schema:
        type: string
        format: uuid
        example: e49350c8-942b-4c38-b1b7-98f7d4547483