In previous lessons, we built a simple FastAPI application, defined endpoints, and interacted with a mock database. Today, we'll dive into the concept of parameters and how they can enhance our API functionality.
Parameters enable APIs to accept input that can alter their behavior and outputs. Essentially, they allow us to customize the data retrieval or operations performed by the API based on specific criteria.
For instance, if you needed to fetch details about a specific crew member by their id
within our mock database, parameters would be the mechanism to achieve this. Let's explore this concept further.
Parameters in APIs primarily come in two basic flavors: Path Parameters and Query Parameters. While parameters can also be passed through headers and the request body, for now, we will focus on path and query parameters.
Path Parameters: Sometimes called URL parameters, these are variables embedded right into the URL path, following a certain syntax.
/crew_path/{crew_id}
, where {crew_id}
is a path parameter.Query Parameters: These are added to the end of a URL following a ?
, allowing multiple parameters separated by &
.
/crew_query/member?crew_id=x
, where crew_id=x
is a query parameter.Typically, path parameters are part of the API's base URL, while query parameters allow users to customize their data requests. Now, let's see how we can utilize these parameters with FastAPI.
FastAPI provides a straightforward way to incorporate path parameters into endpoint definitions.
Let's see an example:
Python1@app.get("/crew_path/{crew_id}") 2def read_crew_member_by_path(crew_id: int): 3 for member in crew: 4 if member["id"] == crew_id: 5 return member 6 return {"message": "Crew member not found"}
In this example, /crew_path/{crew_id}
is our path with {crew_id}
as the path parameter. crew_id: int
tells FastAPI that we want the crew_id
in the path to be converted to an integer. After receiving a crew_id
, the function iterates through the crew
list and checks if the crew_id
matches any member's id
. If found, it returns that member's data; if not, it returns a "not found" message.
To retrieve data using the path parameter endpoint, you need to include the crew_id
within the URL path. For instance, to request information about the crew member with an ID of 1
, you would use the following URL:
Plain text1localhost:8000/crew_path/1
This structure places the crew_id
directly in the URL path, triggering the read_crew_member_by_path
function to process the request.
Creating an endpoint with query parameters is just as easy in FastAPI. Directly define the parameter in the function using the standard function definition syntax, specifying the type of the parameter (e.g., int
):
Python1@app.get("/crew_query/member") 2def read_crew_member_by_query(crew_id: int): 3 for member in crew: 4 if member["id"] == crew_id: 5 return member 6 return {"message": "Crew member not found"}
In this case, FastAPI will expect a crew_id
query parameter in the URL. Again, it iterates through the crew
list and checks if a crew_id
matches any member's id
and returns that member's data or a "not found" message if crew_id
is not found.
The use of /member
in the path clarifies that we are retrieving data for a specific crew member, although it is optional and provided for added clarity. Query parameters are appended to the URL with a ?
, allowing us to pass the crew_id
value.
For the query parameter endpoint, you will include the crew_id
as part of the URL query string. If you want to fetch details for the crew member with an ID of 1
, your URL will look like this:
Plain text1localhost:8000/crew_query/member?crew_id=1
Here, the crew_id
is passed as a query parameter, prompting the read_crew_member_by_query
function to handle the request.
Advantages:
/crew_path/1
, 1
is a RESTful parameter that directly refers to a specific crew member's ID within the crew resource.Disadvantages:
Advantages:
Disadvantages:
To help you compare and contrast how path and query parameters work within a complete FastAPI application, here's a full implementation:
Python1from fastapi import FastAPI 2 3# Initialize a FastAPI app instance 4app = FastAPI() 5 6# Mock database of crew members 7crew = [ 8 {"id": 1, "name": "Cosmo", "role": "Captain"}, 9 {"id": 2, "name": "Alice", "role": "Engineer"}, 10 {"id": 3, "name": "Bob", "role": "Scientist"} 11] 12 13# Endpoint to get a crew member by path parameter 14@app.get("/crew_path/{crew_id}") # /crew_path/1 15def read_crew_member_by_path(crew_id: int): 16 for member in crew: 17 if member["id"] == crew_id: 18 return member 19 return {"message": "Crew member not found"} 20 21# Endpoint to get a crew member by query parameter 22@app.get("/crew_query/member") # /crew_query/member?crew_id=1 23def read_crew_member_by_query(crew_id: int): 24 for member in crew: 25 if member["id"] == crew_id: 26 return member 27 return {"message": "Crew member not found"}
Now you can see how both types of parameters—path and query—are integrated within a real FastAPI application.
Awesome job! You've learned how to use path and query parameters to retrieve specific data in FastAPI applications. We've learned the differences between path and query parameters, and how each can be applied to create flexible and functional API endpoints.
Remember, practicing is fundamental to learning, and in the exercises that follow, you'll put what you've learned into practice! Let's delve into the exercises with enthusiasm. You've got this!