Working with Path and Query Parameters

Welcome to the another lesson of this course. In our previous lessons, we established a foundation by learning about RESTful APIs and making GET requests with the requests library. Now, we will shift our focus to path and query parameters, essential tools for refining API requests and fetching specific data.

Path and query parameters play a crucial role in making your API requests more precise and efficient. Imagine you are shopping online: selecting a specific item using its ID is akin to a path parameter, while filtering items by categories like price or color resembles query parameters. In this lesson, we'll explore these concepts with practical examples, empowering you to extract just the information you need from an API.

Path parameters are part of the URL used to access specific resources within an API, acting like unique identifiers. For example, if you want to retrieve a to-do item with ID 3, the URL would be structured as follows:

http://localhost:8000/todos/3

In this case, 3 is the path parameter specifying the particular item you wish to access.

Query parameters are added to the URL after a ? to filter or modify the data returned by the API. They are formatted as key-value pairs. For instance, if you want to list only the completed to-do tasks, your request would be:

http://localhost:8000/todos?done=true

Here, done=true is the query parameter filtering the results to include only tasks that are marked as completed.

Before jumping into implementing these parameters using Python's requests library, let's make sure everything's set up. Start by importing the requests library and defining the base URL:

import requests

# Base URL for the API
base_url = "http://localhost:8000"

Now we're all set to dive into the code examples!

Path parameters are used to target specific resources within an API, allowing you to access individual items directly. They are appended directly to the endpoint URL. For instance, if you want to fetch details of a specific to-do item using its ID, you'd use a path parameter.

Here's a practical example using ID 3:

# Define the ID of the todo item you want to retrieve
todo_id = 3

# Make a GET request using the path parameter for the specific todo item
response = requests.get(f"{base_url}/todos/{todo_id}")

# Check if the request was successful
if response.status_code == 200:
    # Parse the JSON response to get details of the todo item
    todo = response.json()

    # Print all details of the todo item
    print(f"ID: {todo['id']}")
    print(f"Title: {todo['title']}")
    print(f"Description: {todo['description']}")
    print(f"Done: {todo['done']}")
else:
    # Handle potential errors
    print("Error fetching the todo with path parameter")
    print(f"Status Code: {response.status_code}")
    print(f"Error Details: {response.json()}")

In this example, the todo_id is a path parameter specifying the to-do item with ID 3, and the full URL looks like http://localhost:8000/todos/3. If successful, you'll get an output displaying the task details:

ID: 3
Title: Finish project report
Description: Summarize Q4 performance metrics
Done: False

This output confirms that the specific item was retrieved, demonstrating how path parameters enable you to access individual resources accurately.