openapi: 3.1.1
info:
  title: Recipe API
  description: Programmatic access to a database of recipes. Users can publish and find recipes.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.recipes.bitfield.eu/v1
security: []
tags:
  - name: Recipe
    description: Steps and ingredients for preparing a dish
  - name: Account
    description: Access to protected operations
paths:
  /recipe/new:
    post:
      tags:
        - Recipe
      summary: Add a recipe
      operationId: addRecipe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recipe'
            examples:
              recipeIn:
                $ref: '#/components/examples/HummusV1In'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
              examples:
                recipeOut:
                  $ref: '#/components/examples/HummusV1Out'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
        - httpBasic: []
  /recipe/search:
    get:
      tags:
        - Recipe
      summary: Find recipes
      operationId: FindRecipes
      parameters:
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: Category name filter (equals, ignores case)
        - name: recipe
          in: query
          required: false
          schema:
            type: string
          description: Recipe name filter (contains, ignores case)
        - name: limit
          in: query
          required: true
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 100
          description: Maximum number of recipes to return
        - name: offset
          in: query
          required: true
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Index into result set from where recipes will start to be returned
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipe'
              examples:
                dipsOut:
                  $ref: '#/components/examples/DipsOut'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
  /recipe/{recipeId}:
    get:
      tags:
        - Recipe
      summary: Get a recipe
      operationId: GetRecipe
      parameters:
        - $ref: '#/components/parameters/{recipeId}'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
              examples:
                recipeOut:
                  $ref: '#/components/examples/HummusV1Out'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
    put:
      tags:
        - Recipe
      summary: Update a recipe
      operationId: UpdateRecipe
      parameters:
        - $ref: '#/components/parameters/{recipeId}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Recipe'
            examples:
              recipeIn:
                $ref: '#/components/examples/HummusV2In'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipe'
              examples:
                recipeOut:
                  $ref: '#/components/examples/HummusV2Out'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
        - httpBasic: []
    delete:
      tags:
        - Recipe
      summary: Remove a recipe
      operationId: RemoveRecipe
      parameters:
        - $ref: '#/components/parameters/{recipeId}'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
        - httpBasic: []
  /account/register:
    post:
      tags:
        - Account
      summary: Register an account
      operationId: RegisterAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
            examples:
              accountIn:
                $ref: '#/components/examples/AccountIn'
        required: true
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
components:
  securitySchemes:
    httpBasic:
      type: http
      scheme: basic
  schemas:
    Id:
      type: integer
      format: int64
    NonBlankString:
      type: string
      pattern: ^(.|\s)*\S(.|\s)*$
    DateTime:
      type: string
      format: date-time
    Recipe:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
          readOnly: true
          description: Unique identifier of the recipe
        name:
          $ref: '#/components/schemas/NonBlankString'
          description: Name
        description:
          $ref: '#/components/schemas/NonBlankString'
          description: Description
        changedAt:
          $ref: '#/components/schemas/DateTime'
          readOnly: true
          description: Last point in time when the recipe was changed
        categories:
          type: array
          items:
            $ref: '#/components/schemas/NonBlankString'
          description: Category names
        ingredients:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/NonBlankString'
          description: Step descriptions
        steps:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/NonBlankString'
          description: Ingredient names
      required:
        - name
        - description
        - categories
        - ingredients
        - steps
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          description: URI reference that identifies the problem type.
          format: uri
        status:
          type: integer
          description: HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
        title:
          type: string
          description: Short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization.
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        properties:
          type: object
          description: Map for additional, non-standard properties
      required:
        - title
    Email:
      type: string
      format: email
      description: Email address
    Password:
      type: string
      format: password
      minLength: 8
      description: Password
    Account:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/Email'
        password:
          $ref: '#/components/schemas/Password'
      required:
        - email
        - password
  examples:
    HummusV1In:
      summary: Hummus recipe
      value:
        name: Hummus
        description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
        categories:
          - Dip
          - Spread
        ingredients:
          - Chickpeas
          - Tahini
          - Olive oil
          - Lemon juice
          - Garlic
        steps:
          - Combine chickpeas, tahini, olive oil, lemon juice, garlic, and salt in a food processor.
          - Blend until smooth, slowly adding cold water until you reach a creamy consistency.
          - Taste and adjust seasoning if needed.
    HummusV1Out:
      summary: Hummus recipe
      value:
        id: 1729
        name: Hummus
        description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
        changedAt: '2025-08-08T15:35:10.294411Z'
        categories:
          - Dip
          - Spread
        ingredients:
          - Chickpeas
          - Tahini
          - Olive oil
          - Lemon juice
          - Garlic
        steps:
          - Combine chickpeas, tahini, olive oil, lemon juice, garlic, and salt in a food processor.
          - Blend until smooth, slowly adding cold water until you reach a creamy consistency.
          - Taste and adjust seasoning if needed.
    DipsOut:
      summary: Dip category search
      value:
        - id: 3
          name: Muhammara
          description: Muhammara is a vibrant and flavorful dip or spread from the Middle East, particularly popular in Syrian and Turkish cuisine. It's made primarily from roasted red bell peppers, walnuts, breadcrumbs, and pomegranate molasses.
          changedAt: '2025-08-08T16:24:44.673034Z'
          categories:
            - Dip
          ingredients:
            - Pomegranate molasses
            - Red bell peppers
            - Bread crumbs
            - Cumin
            - Chili flakes
            - Garlic
            - Walnuts
            - Lemon juice
          steps:
            - Roast whole bell peppers in an oven or air fryer and wait until blackened on the outside.
            - Put the peppers in a bowl cover them with to let steam and cool down
            - Remove core seeds, and skins
            - Combine all the ingredients in a food processor.
            - Process until mostly smooth but with a little texture remaining.
            - Taste and adjust flavor as needed (lemon for acidity, pomegranate molasses for sweetness)
        - id: 2
          name: Hummus
          description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
          changedAt: '2025-08-08T16:24:44.579213Z'
          categories:
            - Dip
          ingredients:
            - Chickpeas
            - Tahini
            - Lemon juice
            - Garlic
          steps:
            - Combine chickpeas, tahini, lemon juice, garlic, and salt in a food processor.
            - Blend until smooth, slowly adding cold water until you reach a creamy consistency.
            - Taste and adjust seasoning if needed.
    HummusV2In:
      summary: Hummus recipe update
      value:
        name: Hummus
        description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
        categories:
          - Dip
          - Spread
        ingredients:
          - Chickpeas
          - Tahini
          - Lemon juice
          - Garlic
        steps:
          - Combine chickpeas, tahini, lemon juice, garlic, and salt in a food processor.
          - Blend until smooth, slowly adding cold water until you reach a creamy consistency.
          - Taste and adjust seasoning if needed.
    HummusV2Out:
      summary: Hummus recipe update
      value:
        id: 1729
        name: Hummus
        description: Hummus, is a Levantine dip, spread, or savory dish made from cooked, mashed chickpeas blended with tahini, lemon juice, and garlic.
        changedAt: '2025-08-09T12:48:32.134821Z'
        categories:
          - Dip
          - Spread
        ingredients:
          - Chickpeas
          - Tahini
          - Lemon juice
          - Garlic
        steps:
          - Combine chickpeas, tahini, lemon juice, garlic, and salt in a food processor.
          - Blend until smooth, slowly adding cold water until you reach a creamy consistency.
          - Taste and adjust seasoning if needed.
    AccountIn:
      summary: Account registration
      value:
        email: ada@example.com
        password: FBR5h0L1ENA3edctgDIEnxSvFdR0
  parameters:
    '{recipeId}':
      name: recipeId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
      description: Unique identifier of the recipe