Recipe Retrieval Endpoints

Welcome to the first lesson of the Building the Recipe API course! In this lesson, you will learn how to build the core endpoints that allow your app to fetch recipes and their details from a database.

Recipe retrieval is a fundamental feature of any cooking helper app. Users need to be able to look up recipes, see what ingredients are required, and follow the steps to cook a dish. By the end of this lesson, you will know how to create endpoints that return a single recipe by its ID and a list of recipes with pagination. These skills are the foundation for more advanced features you’ll add later, such as searching, filtering, and user reviews.

Before we dive in, let’s briefly recall two key concepts you’ll use in this lesson: Flask routes and SQLAlchemy models.

• Flask routes are functions that respond to specific URLs in your web application. For example, when a user visits /api/recipes/1, a route function will handle that request and return the recipe with ID 1.
• SQLAlchemy models are Python classes that represent tables in your database. For example, you might have a Recipe model for recipes and an Ingredient model for ingredients. These models make it easy to query and update your database using Python code.

You’ll see both of these concepts in action as we build the recipe retrieval endpoints.

Let’s start by building an endpoint that returns a single recipe by its ID. This is useful when a user wants to view the details of a specific recipe.

In Flask, you define a route using the @routes.route decorator. Here’s how you set up a route to handle requests like /api/recipes/1:

@routes.route('/api/recipes/<int:recipe_id>', methods=['GET'])
def get_recipe(recipe_id):
    # Function body will go here

• The <int:recipe_id> part means that this route will match any integer value in the URL and pass it to the function as recipe_id.
• The methods=['GET'] part means this route only responds to GET requests.

Inside the route function, you need to fetch the recipe from the database using its ID. You can do this with SQLAlchemy’s query.get_or_404() method:

recipe = Recipe.query.get_or_404(recipe_id)

• This line tries to find a recipe with the given ID. If it doesn’t exist, Flask will automatically return a 404 error.

Suppose your app allows users to rate recipes. You might want to show the average rating for each recipe. Here’s how you can calculate it:

from sqlalchemy import func

avg_rating = (
    db.session.query(func.avg(Review.rating))
    .filter(Review.recipe_id == recipe.id)
    .scalar()
)
average = round(avg_rating, 2) if avg_rating is not None else None

• func.avg(Review.rating) calculates the average rating for the recipe.
• .filter(Review.recipe_id == recipe.id) ensures you only consider reviews for this recipe.
• .scalar() gets the result as a single value.
• If there are no ratings, average will be None.

Now, you need to return the recipe details as a JSON object. Here’s how you can do it:

response = {
    'id': recipe.id,
    'name': recipe.name,
    'ingredients': [i.name for i in recipe.ingredients],
    'steps': recipe.steps,
    'average_rating': average
}
return jsonify(response), 200

• The ingredients field is a list of ingredient names.
• The steps field contains the cooking instructions.
• The average_rating field shows the average rating or None if there are no ratings.

Example Output:

{
  "id": 1,
  "name": "Spaghetti Carbonara",
  "ingredients": ["spaghetti", "eggs", "bacon", "parmesan"],
  "steps": "1. Boil pasta. 2. Cook bacon. 3. Mix eggs and cheese. 4. Combine all.",
  "average_rating": 4.5
}

This is what a user would see if they requested a specific recipe.

Next, let’s build an endpoint that returns a list of recipes, but only a few at a time. This is called pagination, and it helps your app handle large numbers of recipes without overwhelming the user or the server.

You can set up a route for /api/recipes that accepts optional query parameters for pagination:

@routes.route('/api/recipes', methods=['GET'])
def get_all_recipes_paginated():
    page = request.args.get('page', default=1, type=int)
    per_page = request.args.get('per_page', default=10, type=int)
    # Function body will go here

• page will control which page we return, request.args.get('page', default=1, type=int) gets the page number from the URL, defaulting to 1.
• per_page controls how many recipes to show per page, defaulting to 10 as shown in the code.

Use SQLAlchemy’s paginate method to get the right set of recipes:

pagination = Recipe.query.paginate(page=page, per_page=per_page, error_out=False)

• This returns a pagination object with the recipes for the current page and information about the total number of recipes.

Now, build a JSON response that includes the recipes and pagination info:

recipes = []
for recipe in pagination.items:
    recipes.append({
        'id': recipe.id,
        'name': recipe.name,
        'ingredients': [i.name for i in recipe.ingredients],
        'steps': recipe.steps
    })

return jsonify({
    'recipes': recipes,
    'total': pagination.total,
    'page': pagination.page,
    'per_page': pagination.per_page,
    'pages': pagination.pages,
    'has_next': pagination.has_next,
    'has_prev': pagination.has_prev
}), 200

• The recipes list contains the recipes for the current page.
• The response also includes total (the total number of recipes), page (the current page), per_page (recipes per page), pages (total pages), and flags for has_next and has_prev.

Example Output:

{
  "recipes": [
    {
      "id": 1,
      "name": "Spaghetti Carbonara",
      "ingredients": ["spaghetti", "eggs", "bacon", "parmesan"],
      "steps": "1. Boil pasta. 2. Cook bacon. 3. Mix eggs and cheese. 4. Combine all."
    },
    {
      "id": 2,
      "name": "Tomato Soup",
      "ingredients": ["tomatoes", "onion", "garlic", "cream"],
      "steps": "1. Cook tomatoes. 2. Add onion and garlic. 3. Blend. 4. Add cream."
    }
  ],
  "total": 25,
  "page": 1,
  "per_page": 2,
  "pages": 13,
  "has_next": true,
  "has_prev": false
}

This allows users to browse recipes page by page.

In this lesson, you learned how to build two essential endpoints for your cooking helper app:

• One to fetch a single recipe by its ID, including its ingredients and average rating.
• Another to list all recipes with pagination, making it easy to browse through many recipes.

These endpoints are the backbone of your app’s recipe retrieval features. In the practice exercises that follow, you’ll get hands-on experience implementing and testing these endpoints yourself. This will help you get comfortable with Flask routes, SQLAlchemy queries, and formatting JSON responses — skills you’ll use throughout the rest of the course. Good luck, and have fun building your cooking helper!