Welcome back! In the last lesson, you learned how to build basic endpoints to retrieve recipes from your database, including fetching a single recipe by its ID and listing recipes with pagination. These are the building blocks of any recipe API.

Now, let’s take things a step further. Imagine you open a cooking app and want to find recipes that use only the ingredients you have in your kitchen. Or maybe you want to see the steps of a recipe as a list so you can follow them one by one. These features make your app much more helpful and user-friendly.

In this lesson, you’ll learn how to:

• Search for recipes by a list of ingredients.
• Return recipe steps as an array, not just a long string.

These skills will help you build a smarter, more flexible recipe API.

Before we dive in, let’s quickly remind ourselves how our data is organized. This will help you understand how searching and filtering work.

• Recipe: Each recipe has an id, a name, a steps field (which is a string with all the steps), and a list of ingredients.
• Ingredient: Each ingredient has an id and a name. Ingredients are linked to recipes through a many-to-many relationship.
• Review: Each review is linked to a recipe and has a rating.

Here’s a simplified look at the models (using SQLAlchemy):

from sqlalchemy import Table, Column, Integer, String, Text, ForeignKey
from sqlalchemy.orm import relationship, declarative_base

Base = declarative_base()

recipe_ingredient = Table(
    'recipe_ingredient',
    Base.metadata,
    Column('recipe_id', Integer, ForeignKey('recipe.id'), primary_key=True),
    Column('ingredient_id', Integer, ForeignKey('ingredient.id'), primary_key=True)
)

class Ingredient(Base):
    __tablename__ = 'ingredient'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    recipes = relationship('Recipe', secondary=recipe_ingredient, back_populates='ingredients')

class Recipe(Base):
    __tablename__ = 'recipe'
    id = Column(Integer, primary_key=True)
    name = Column(String(100))
    ingredients = relationship('Ingredient', secondary=recipe_ingredient, back_populates='recipes')
    steps = Column(Text)

• The recipe_ingredient table connects recipes and ingredients.
• Each recipe can have many ingredients, and each ingredient can be used in many recipes.

This structure is important for searching recipes by ingredients.

Many apps and websites want to show recipe steps one at a time, not as a single long string. To help with this, you can create an endpoint that returns the steps as a list.

First, get the recipe by its ID:

@router.get("/recipes/{recipe_id}/steps", response_model=StepsOut)
def get_recipe_steps_array(recipe_id: int, db: Session = Depends(get_db)):
    recipe = db.get(Recipe,recipe_id)
    if not recipe:
        raise HTTPException(status_code=404, detail="Recipe not found")

• If the recipe does not exist, a 404 error is raised.

Assume the steps are stored as a string, with each step on a new line. You can split this string into a list:

    steps_list = []
    if recipe.steps:
        steps_list = [s.strip() for s in recipe.steps.split("\n") if s.strip()]

• split("\n") breaks the string into lines.
• strip() removes any extra spaces.
• The list comprehension skips any empty lines.

Return the steps as a structured response using a response model. First, define the response classes (Pydantic models) for the steps. For example::

class StepsOut(BaseModel):
    recipe_id: int
    name: Optional[str] = None
    steps: List[str]

Then, you can use these classes to build and return the steps:

    return StepsOut(recipe_id=recipe.id, name=recipe.name, steps=steps_list)

Example output:

{
  "recipe_id": 2,
  "name": "Tomato Basil Soup",
  "steps": [
    "Chop tomatoes.",
    "Add basil.",
    "Simmer for 20 minutes."
  ]
}

This structure allows clients (like web or mobile apps) to easily loop through the steps and present them to users in a clear, step-by-step format.

Let’s say you want to find all recipes that use a specific set of ingredients, like "tomato" and "basil". You’ll need an endpoint that takes a list of ingredient names and returns only the recipes that use all of them.

First, you need to accept a list of ingredient names from the user. You can do this by creating a POST endpoint that expects a JSON body.

@router.post("/recipes/by-ingredients", response_model=List[RecipeOut])
def get_recipes_by_ingredients(payload: IngredientsIn, db: Session = Depends(get_db)):
    if not payload.ingredients:
        raise HTTPException(status_code=400, detail='Missing "ingredients" in request')

    ingredient_names = [name.strip().lower() for name in payload.ingredients if name.strip()]
    if not ingredient_names:
        raise HTTPException(status_code=400, detail="Empty ingredients list")

• The request body is parsed and validated using a Pydantic model.
• All ingredient names are converted to lowercase for case-insensitive matching.

Example input:

{
  "ingredients": ["Tomato", "Basil"]
}

Next, you need to find the IDs of the ingredients that match the names provided.

    # Find all matching ingredients (case-insensitive)
    ingredient_objs = db.query(Ingredient).filter(func.lower(Ingredient.name).in_(ingredient_names)).all()
    ingredient_ids = [i.id for i in ingredient_objs]
    if not ingredient_ids:
        return []

• This code looks up all ingredients in the database whose names match the ones in the list.
• If no ingredients are found, we return an empty list.

Now, you want to find recipes that use all the specified ingredients. This is done using a subquery:

    subq = (
        db.query(
            recipe_ingredient.c.recipe_id.label("recipe_id"),
            func.count(func.distinct(func.lower(Ingredient.name))).label("match_count"),
        )
        .join(Ingredient, recipe_ingredient.c.ingredient_id == Ingredient.id)
        .filter(func.lower(Ingredient.name).in_(ingredient_names))
        .group_by(recipe_ingredient.c.recipe_id)
        .subquery()
    )

    recipes = (
        db.query(Recipe)
        .join(subq, Recipe.id == subq.c.recipe_id)
        .filter(subq.c.match_count == len(ingredient_names))
        .all()
    )

• The subquery counts how many of the requested ingredients each recipe uses.
• Only recipes where the count matches the number of ingredients requested are selected. This ensures the recipe uses all the ingredients.

Finally, you return the matching recipes using a response model and a serialization helper.

For the response model, we will use an array of RecipeOut, created earlier in this course:

class RecipeOut(BaseModel):
    id: int
    name: Optional[str] = None
    ingredients: List[str] = []
    steps: Optional[str] = None

For serializing the recipes, we can implement a simple function that builds a RecipeOut given a Recipe:

def serialize_recipe(recipe: Recipe) -> RecipeOut:
    return RecipeOut(
        id=recipe.id,
        name=recipe.name,
        ingredients=[i.name for i in recipe.ingredients],
        steps=recipe.steps,
    )

Finally, we can implement the response for the function

    return [serialize_recipe(r) for r in recipes]

Example output:

[
  {
    "id": 2,
    "name": "Tomato Basil Soup",
    "ingredients": ["Tomato", "Basil", "Garlic"],
    "steps": "Chop tomatoes...\nAdd basil..."
  }
]

If no recipes match, you’ll get an empty list: [].

In this lesson, you learned how to:

• Return recipe steps as an array, making it easier for users to follow each step.
• Search for recipes by a list of ingredients, returning only those that use all the specified ingredients.

These features make your recipe API much more useful and user-friendly. Up next, you’ll get to practice building and testing these endpoints yourself. This hands-on practice will help you solidify your understanding and prepare you for even more advanced features. Good luck!