FastAPI Crash Course: An Introduction

By /

Okay, here’s a comprehensive article on a “FastAPI Crash Course: An Introduction,” designed to be approximately 5000 words and delve deeply into the fundamentals:

FastAPI Crash Course: An Introduction – Building Modern APIs with Python

The world of web development is constantly evolving, and the demand for efficient, high-performance APIs is greater than ever. Enter FastAPI, a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints. This crash course provides a comprehensive introduction to FastAPI, guiding you from the absolute basics to building functional and robust APIs.

Why FastAPI? The Advantages

Before diving into the technical details, let’s understand why FastAPI has gained such immense popularity in a relatively short time. It boasts a compelling set of advantages:

  • Speed: FastAPI is incredibly fast, on par with NodeJS and Go, thanks to its foundation on Starlette (for request handling) and Pydantic (for data validation). This speed translates to lower latency and improved user experience.
  • Automatic Data Validation: Using Python type hints, FastAPI automatically validates request data, ensuring that the data your API receives conforms to the expected types and structure. This reduces boilerplate code and prevents common errors.
  • Automatic Documentation (Swagger UI and ReDoc): FastAPI automatically generates interactive API documentation using the OpenAPI standard. This documentation is accessible through Swagger UI and ReDoc, making it easy for developers to understand and use your API. No more manual documentation updates!
  • Type Hints and Editor Support: The reliance on Python type hints provides excellent editor support, including autocompletion, type checking, and error detection. This significantly improves developer productivity and reduces debugging time.
  • Easy to Learn and Use: FastAPI has a clean and intuitive API, making it relatively easy to learn and use, even for developers new to building APIs. The documentation is exceptionally well-written and comprehensive.
  • Dependency Injection System: FastAPI has a powerful yet easy-to-use dependency injection system. This allows you to easily manage dependencies, such as database connections, authentication services, and more.
  • Security and Authentication: FastAPI provides built-in support for common security and authentication mechanisms, including OAuth2 with JWT tokens, API keys, and HTTP Basic authentication.
  • Asynchronous Support: FastAPI fully supports asynchronous code using async and await, allowing you to write non-blocking code that can handle a large number of concurrent requests.
  • Testing: FastAPI is designed to be easily testable, and integrates seamlessly with testing frameworks like Pytest.
  • Standards-Based: Built upon open standards like OpenAPI (formerly Swagger) and JSON Schema. This ensures compatibility and interoperability with a wide range of tools and services.

Getting Started: Installation and Setup

The first step is to install FastAPI and Uvicorn, an ASGI (Asynchronous Server Gateway Interface) server that will run our FastAPI application. ASGI is the successor to WSGI, designed for asynchronous applications.

bash
pip install fastapi uvicorn

Your First FastAPI Application

Let’s create a simple “Hello, World!” application to understand the basic structure:

“`python

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get(“/”)
async def root():
return {“message”: “Hello, World!”}
“`

Let’s break down this code:

  1. from fastapi import FastAPI: Imports the FastAPI class.
  2. app = FastAPI(): Creates an instance of the FastAPI class. This instance, app, is your main point of interaction with FastAPI.
  3. @app.get("/"): This is a decorator. It tells FastAPI that the function below (root) should handle requests that:
    • Use the GET HTTP method.
    • Go to the path / (the root path).
  4. async def root():: This defines the path operation function.
    • async def: This indicates that the function is asynchronous. While not strictly necessary for this simple example, it’s good practice to use async for I/O-bound operations (like database queries or network requests) to prevent blocking the main thread.
    • root(): The name of the function. The name doesn’t directly affect the API, but it’s good practice to choose a descriptive name.
    • return {"message": "Hello, World!"}: This is the response that will be sent back to the client. FastAPI automatically converts this Python dictionary into a JSON response.

Running the Application

To run the application, use the following command in your terminal (from the same directory where main.py is located):

bash
uvicorn main:app --reload

Let’s break down this command:

  • uvicorn: This is the ASGI server we installed earlier.
  • main:app: This tells Uvicorn where to find the FastAPI application:
    • main: The name of the Python file (without the .py extension).
    • app: The name of the FastAPI instance within that file.
  • --reload: This enables “auto-reload.” Whenever you make changes to your code, Uvicorn will automatically restart the server, making development much faster.

Now, open your web browser and go to http://127.0.0.1:8000/. You should see the JSON response: {"message": "Hello, World!"}.

Interactive API Documentation

One of FastAPI’s most compelling features is the automatic API documentation. Access it by going to:

  • Swagger UI: http://127.0.0.1:8000/docs
  • ReDoc: http://127.0.0.1:8000/redoc

Swagger UI provides an interactive interface where you can explore your API’s endpoints, see the expected request and response formats, and even try out the API directly from the browser. ReDoc offers a more traditional, read-only documentation format.

Path Parameters

Path parameters are parts of the URL path that can vary. They are used to identify specific resources.

“`python

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get(“/items/{item_id}”)
async def read_item(item_id: int):
return {“item_id”: item_id}
“`

In this example:

  • {item_id} in the path /items/{item_id} is a path parameter.
  • item_id: int in the function signature declares the path parameter and its type. FastAPI will:
    • Extract the value of item_id from the URL.
    • Convert it to an integer.
    • Pass it to the read_item function.
    • Validate that the value is indeed an integer. If not, it will return a clear error message.

Now, if you go to http://127.0.0.1:8000/items/5, you’ll get {"item_id": 5}. If you go to http://127.0.0.1:8000/items/foo, you’ll get a detailed error message indicating that “foo” could not be converted to an integer. This automatic validation is a huge benefit!

Query Parameters

Query parameters are key-value pairs appended to the URL after a question mark (?). They are often used for filtering, sorting, or pagination.

“`python

main.py

from fastapi import FastAPI
from typing import Union

app = FastAPI()

@app.get(“/items/”)
async def read_items(skip: int = 0, limit: int = 10, q: Union[str, None] = None):
return {“skip”: skip, “limit”: limit, “q”: q}
“`

In this example:

  • skip, limit, and q are query parameters.
  • skip: int = 0: skip is an integer with a default value of 0.
  • limit: int = 10: limit is an integer with a default value of 10.
  • q: Union[str, None] = None: q can be either a string or None (meaning it’s optional), with a default value of None. The Union type hint indicates that it can be one of several types.

Now, you can access the API with different query parameters:

  • http://127.0.0.1:8000/items/: Returns {"skip": 0, "limit": 10, "q": null}
  • http://127.0.0.1:8000/items/?skip=20: Returns {"skip": 20, "limit": 10, "q": null}
  • http://127.0.0.1:8000/items/?limit=5&q=hello: Returns {"skip": 0, "limit": 5, "q": "hello"}

Request Body

To send data to the API (e.g., when creating or updating a resource), you use the request body. FastAPI uses Pydantic models to define the structure and types of the request body.

“`python

main.py

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: Union[float, None] = None

app = FastAPI()

@app.post(“/items/”)
async def create_item(item: Item):
return item
“`

Let’s break this down:

  1. from pydantic import BaseModel: Imports the BaseModel class from Pydantic.
  2. class Item(BaseModel):: Defines a Pydantic model called Item. This model represents the structure of the data we expect in the request body.
    • name: str: The item must have a name field, which must be a string.
    • description: Union[str, None] = None: The item can optionally have a description field, which can be a string or None.
    • price: float: The item must have a price field, which must be a float.
    • tax: Union[float, None] = None: The item can optionally have a tax field, which can be a float or None.
  3. @app.post("/items/"): This uses the POST HTTP method, which is typically used for creating resources.
  4. async def create_item(item: Item):: The item parameter is declared with the type Item. FastAPI will:
    • Read the request body.
    • Parse it as JSON.
    • Validate that it conforms to the Item model.
    • Convert it into an instance of the Item class.
    • Pass that instance to the create_item function.
  5. return item: Returns the received Item object. FastAPI will automatically serialize it back into JSON.

To test this, you can use Swagger UI (http://127.0.0.1:8000/docs). It will show you the expected request body format. You can also use tools like curl or Postman:

bash
curl -X POST -H "Content-Type: application/json" -d '{"name": "Awesome Gadget", "price": 99.99}' http://127.0.0.1:8000/items/

This will return:

json
{
"name": "Awesome Gadget",
"description": null,
"price": 99.99,
"tax": null
}

If you send invalid data (e.g., a string for price), you’ll get a clear error message explaining the problem.

Combining Path, Query, and Request Body Parameters

You can use path parameters, query parameters, and a request body all in the same path operation:

“`python

main.py

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Union

class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: Union[float, None] = None

app = FastAPI()

@app.put(“/items/{item_id}”)
async def update_item(item_id: int, item: Item, q: Union[str, None] = None):
result = {“item_id”: item_id, “item”: item, “q”: q}
return result
“`

In this example:

  • PUT is used, typically for updating resources.
  • item_id is a path parameter.
  • item is the request body (an Item object).
  • q is an optional query parameter.

Response Model

You can also specify the structure of the response using a Pydantic model. This provides additional validation and documentation.

“`python

main.py

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Union

class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: Union[float, None] = None

class ItemOut(BaseModel):
name: str
price: float

app = FastAPI()

@app.post(“/items/”, response_model=ItemOut)
async def create_item(item: Item):
return item
“`

In this example:

  • ItemOut defines the response model. It only includes the name and price fields.
  • response_model=ItemOut in the decorator tells FastAPI to use this model for the response.
  • Even though we return the entire item object, FastAPI will filter it to include only the fields defined in ItemOut.

This is useful for:

  • Hiding sensitive data: You might not want to return certain fields (e.g., passwords) in the response.
  • Ensuring consistency: The response will always conform to the specified model.
  • Documentation: The response model is clearly documented in Swagger UI and ReDoc.

Handling Errors

FastAPI provides a convenient way to handle errors using the HTTPException class:

“`python
from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {“foo”: “The Foo Wrestlers”}

@app.get(“/items/{item_id}”)
async def read_item(item_id: str):
if item_id not in items:
raise HTTPException(status_code=404, detail=”Item not found”)
return {“item”: items[item_id]}
“`

In this example:

  • raise HTTPException(status_code=404, detail="Item not found"): Raises an HTTP exception with a status code of 404 (Not Found) and a custom detail message.
  • FastAPI will automatically convert this exception into a JSON response with the appropriate status code and error details.

You can use any valid HTTP status code (e.g., 400 for Bad Request, 401 for Unauthorized, 500 for Internal Server Error).

Dependency Injection

FastAPI’s dependency injection system is a powerful tool for managing dependencies and promoting code reusability. Dependencies can be anything that your path operation functions need, such as:

  • Database connections
  • Authentication services
  • Request headers
  • Query parameters (you can also inject them directly)

Here’s a simple example:

“`python
from fastapi import FastAPI, Depends, Header
from typing import Union

app = FastAPI()

async def get_db(): # Our dependency
db = {“message”: “Fake Database Connection”} # Pretend Database
try:
yield db
finally:
# close the db connection here in real database
pass

async def verify_token(x_token: str = Header(…)): # Dependency for checking token
if x_token != “fake-super-secret-token”:
raise HTTPException(status_code=400, detail=”X-Token header invalid”)

async def verify_key(x_key: str = Header(…)): # Dependency for checking key
if x_key != “fake-super-secret-key”:
raise HTTPException(status_code=400, detail=”X-Key header invalid”)

@app.get(“/items/”, dependencies=[Depends(verify_token), Depends(verify_key)]) # Route using dependencies
async def read_items(db = Depends(get_db)): # Injecting the db dependency
return db

“`

Explanation:
1. async def get_db():: This is a dependency function. It “provides” a “database connection” (in this case, a fake one). The yield keyword makes this a generator. The code before yield runs before the path operation function. The code after yield (in the finally block) runs after the path operation function, even if there’s an error. This is ideal for managing resources like database connections.
2. async def verify_token(...) and async def verify_key(...): These dependencies verify the presence and validity of custom headers (X-Token and X-Key). The Header(...) is a special dependency provided by FastAPI for accessing request headers. The ... is an ellipsis and is a placeholder. It signals that a value is required.
3. @app.get("/items/", dependencies=[Depends(verify_token), Depends(verify_key)]): This path operation declares two dependencies: verify_token and verify_key. FastAPI will execute these dependencies before calling read_items. If any dependency raises an HTTPException, the request will be aborted, and the error response will be returned.
4. async def read_items(db = Depends(get_db)):: The read_items function depends on get_db. FastAPI will:
* Call get_db().
* Get the value yielded by get_db() (our fake database connection).
* Pass that value as the db argument to read_items.

To test this, you need to include the required headers in your request:

bash
curl -H "X-Token: fake-super-secret-token" -H "X-Key: fake-super-secret-key" http://127.0.0.1:8000/items/

If you omit a header or provide an incorrect value, you’ll get a 400 error.

Dependency Injection – More Complex Example (Database)

Let’s create a slightly more realistic example, simulating interaction with a database (using SQLAlchemy, a popular Python ORM):

“`python

main.py

from typing import List, Union

from fastapi import Depends, FastAPI, HTTPException
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
from pydantic import BaseModel

— Database Setup (SQLite for simplicity) —

DATABASE_URL = “sqlite:///./test.db” # Use an in-memory SQLite database
engine = create_engine(DATABASE_URL, connect_args={“check_same_thread”: False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

— Database Model —

class DBItem(Base):
tablename = “items”
id = Column(Integer, primary_key=True, index=True)
name = Column(String, index=True)
description = Column(String)
price = Column(Integer)

Base.metadata.create_all(bind=engine) # Create the table

— Pydantic Models —

class ItemCreate(BaseModel):
name: str
description: Union[str, None] = None
price: int

class Item(ItemCreate):
id: int
class Config:
orm_mode = True

— Dependency —

def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()

— FastAPI App —

app = FastAPI()

— CRUD Operations —

@app.post(“/items/”, response_model=Item)
def create_item(item: ItemCreate, db: Session = Depends(get_db)):
db_item = DBItem(**item.dict())
db.add(db_item)
db.commit()
db.refresh(db_item)
return db_item

@app.get(“/items/”, response_model=List[Item])
def read_items(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
items = db.query(DBItem).offset(skip).limit(limit).all()
return items

@app.get(“/items/{item_id}”, response_model=Item)
def read_item(item_id: int, db: Session = Depends(get_db)):
db_item = db.query(DBItem).filter(DBItem.id == item_id).first()
if db_item is None:
raise HTTPException(status_code=404, detail=”Item not found”)
return db_item

@app.put(“/items/{item_id}”, response_model=Item)
def update_item(item_id: int, item: ItemCreate, db: Session = Depends(get_db)):
db_item = db.query(DBItem).filter(DBItem.id == item_id).first()
if db_item is None:
raise HTTPException(status_code=404, detail=”Item not found”)

for var, value in item.dict().items():
    setattr(db_item, var, value) if value else None

db.commit()
db.refresh(db_item)
return db_item

@app.delete(“/items/{item_id}”)
def delete_item(item_id: int, db: Session = Depends(get_db)):
db_item = db.query(DBItem).filter(DBItem.id == item_id).first()
if db_item is None:
raise HTTPException(status_code=404, detail=”Item not found”)
db.delete(db_item)
db.commit()
return {“message”: “Item deleted”}

“`
Key improvements and explanations in this more advanced example:

  • Database Setup (SQLAlchemy):
    • DATABASE_URL: Defines the connection string for the database. We’re using SQLite for simplicity, but you could easily switch to PostgreSQL, MySQL, etc.
    • create_engine(): Creates the database engine.
    • SessionLocal: Creates a session factory. Each session represents a “conversation” with the database.
    • Base: The base class for our SQLAlchemy models.
  • Database Model (DBItem):
    • Defines the structure of the items table using SQLAlchemy’s declarative base. Each attribute corresponds to a column in the table.
  • Pydantic Models (ItemCreate, Item):
    • ItemCreate: Used for creating and updating items (doesn’t include the id).
    • Item: Used for representing items retrieved from the database (includes the id). orm_mode = True allows Pydantic to work seamlessly with SQLAlchemy models.
  • Dependency (get_db):
    • Creates a new database session for each request.
    • Uses yield to provide the session to the path operation function.
    • Ensures that the session is closed after the request is handled (in the finally block).
  • CRUD Operations:
    • create_item: Creates a new item in the database.
    • read_items: Retrieves a list of items (with pagination using skip and limit).
    • read_item: Retrieves a single item by ID.
    • update_item: Updates an existing item.
    • delete_item: Deletes an item.
  • Error Handling: HTTPException is raised if an item is not found.
  • Data Validation and Serialization: Pydantic models handle request body validation and both request and response serialization.
  • Type Hinting: Extensive use of type hints for clarity and editor support.
  • Database Interaction: SQLAlchemy is used to interact with the database in a clean and object-oriented way.

To run this, you’ll need to install SQLAlchemy:

bash
pip install sqlalchemy

Then, run the application as before:

bash
uvicorn main:app --reload

You can now use Swagger UI (http://127.0.0.1:8000/docs) to interact with your API and perform CRUD operations on the items table. This example demonstrates a complete, albeit simplified, API with database integration, showcasing the power and elegance of FastAPI.

Background Tasks

Sometimes, you need to perform tasks that don’t need to be part of the immediate request-response cycle. For example, sending emails, processing large files, or updating a cache. FastAPI provides BackgroundTasks for this purpose.

“`python
from fastapi import BackgroundTasks, FastAPI

app = FastAPI()

def write_notification(email: str, message=””):
with open(“log.txt”, mode=”a”) as email_file:
content = f”notification for {email}: {message}\n”
email_file.write(content)

@app.post(“/send-notification/{email}”)
async def send_notification(email: str, background_tasks: BackgroundTasks):
background_tasks.add_task(write_notification, email, message=”some notification”)
return {“message”: “Notification sent in the background”}
“`

  • write_notification is the function we want to run in the background. It takes an email and an optional message and appends it to a file.
  • @app.post("/send-notification/{email}") is the route which will receive requests.
  • background_tasks: BackgroundTasks is a dependency. It receives an instance of BackgroundTasks that we can add tasks to.
  • background_tasks.add_task(write_notification, email, message="some notification") adds our task to the queue. The first parameter is the task function, the rest are its parameters.
  • The function will return immediately with the message. FastAPI will run the task after returning the response.

This provides a non-blocking way to execute tasks after returning a response, improving performance and user experience.

Testing

FastAPI is designed for easy testing. You can use libraries like pytest and FastAPI’s TestClient to write comprehensive tests.

“`python

test_main.py

from fastapi.testclient import TestClient
from main import app # Import your FastAPI app

client = TestClient(app)

def test_read_main():
response = client.get(“/”)
assert response.status_code == 200
assert response.json() == {“message”: “Hello, World!”}

def test_create_item():
response = client.post(
“/items/”,
json={“name”: “Test Item”, “price”: 25.99},
)
assert response.status_code == 200
assert response.json()[“name”] == “Test Item”
assert response.json()[“price”] == 25.99

def test_read_item():
# First, create an item
client.post(“/items/”, json={“name”: “Another Item”, “price”: 10.50})

#Then read the item
response = client.get("/items/1")  # Assuming the first created item has ID 1
assert response.status_code == 200
assert response.json()["name"] == "Test Item"

response = client.get("/items/2")
assert response.status_code == 200
assert response.json()["name"] == "Another Item"

def test_read_item_not_found():
response = client.get(“/items/999”) # Assuming item 999 doesn’t exist
assert response.status_code == 404
assert response.json() == {“detail”: “Item not found”}
To run the tests, first install pytest:
pip install pytest
Then run pytest in your terminal:
pytest
``
* **from fastapi.testclient import TestClient:** Imports theTestClient.
* **client = TestClient(app):** Creates aTestClientinstance, wrapping your FastAPI application.
* **test_…functions:** These are your test functions. Each function should test a specific aspect of your API.
* **client.get(),client.post(), etc.:** These methods simulate HTTP requests to your API.
* **assertstatements:** These check that the responses from your API are as expected.
* The tests cover:
* The root path (/).
* Creating an item (POST /items/).
* Retrieving an item by ID (GET /items/{item_id}`).
* Handling a “not found” error.

Conclusion: Your Journey with FastAPI Begins

This crash course has covered the fundamental concepts of FastAPI, providing you with a solid foundation for building modern, high-performance APIs. You’ve learned about:

  • The advantages of FastAPI.
  • Setting up your development environment.
  • Creating basic API endpoints.
  • Using path parameters, query parameters, and request bodies.
  • Data validation with Pydantic.
  • Automatic API documentation.
  • Dependency injection.
  • Handling errors.
  • Database integration with SQLAlchemy (a more advanced example).
  • Background tasks.
  • Testing your API.

This is just the beginning! FastAPI offers many more advanced features, including:

  • Security: Authentication and authorization (OAuth2, JWT, API keys).
  • WebSockets: For real-time communication.
  • Middleware: For adding custom request processing logic.
  • Custom Responses: Returning different response types (e.g., HTML, files).
  • Advanced Pydantic Usage: More complex data validation and serialization.
  • Deployment: Deploying your FastAPI application to various platforms (Docker, cloud providers).

The official FastAPI documentation (https://fastapi.tiangolo.com/) is an excellent resource for further learning. It’s incredibly well-written, comprehensive, and filled with practical examples.

By mastering FastAPI, you’ll be well-equipped to build robust, scalable, and maintainable APIs that meet the demands of modern web development. Happy coding!

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top