Building Your First REST API with FastAPI
FastAPI has emerged as one of the most popular Python frameworks for building APIs, and for good reason. It combines the simplicity of Flask with the performance of more complex frameworks, all while providing automatic API documentation and type safety. In this guide, we’ll build a complete REST API from scratch and explore what makes FastAPI special.
How Building Your First REST API with FastAPI
Why FastAPI?
FastAPI stands out in the crowded field of Python web frameworks for several compelling reasons. It’s built on modern Python features like type hints and async/await, making it both fast and developer-friendly. The framework automatically generates interactive API documentation using Swagger UI and ReDoc, saving hours of manual documentation work. Performance benchmarks show FastAPI competing with Node.js and Go frameworks, thanks to its use of Starlette and Pydantic under the hood.
Setting Up Your Project
Before we start coding, let’s set up a clean Python environment. Create a new directory for your project and set up a virtual environment:
mkdir fastapi-blog-api
cd fastapi-blog-api
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
Install FastAPI and Uvicorn, the ASGI server we’ll use to run our application:
pip install fastapi uvicorn[standard] pydantic
Building a Blog Post API
Let’s create a practical example by building an API for managing blog posts. We’ll implement all the standard CRUD operations: Create, Read, Update, and Delete.
Create a file named main.py:
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional
from datetime import datetime
app = FastAPI(title="Blog API", version="1.0.0")
# Pydantic models for request/response validation
class PostBase(BaseModel):
title: str
content: str
author: str
tags: List[str] = []
class PostCreate(PostBase):
pass
class Post(PostBase):
id: int
created_at: datetime
updated_at: datetime
class Config:
orm_mode = True
# In-memory database (replace with real database in production)
posts_db = []
post_id_counter = 1
@app.get("/")
def read_root():
return {"message": "Welcome to the Blog API"}
@app.post("/posts/", response_model=Post, status_code=201)
def create_post(post: PostCreate):
global post_id_counter
now = datetime.now()
new_post = {
"id": post_id_counter,
"title": post.title,
"content": post.content,
"author": post.author,
"tags": post.tags,
"created_at": now,
"updated_at": now
}
posts_db.append(new_post)
post_id_counter += 1
return new_post
@app.get("/posts/", response_model=List[Post])
def get_all_posts(skip: int = 0, limit: int = 10):
return posts_db[skip : skip + limit]
@app.get("/posts/{post_id}", response_model=Post)
def get_post(post_id: int):
for post in posts_db:
if post["id"] == post_id:
return post
raise HTTPException(status_code=404, detail="Post not found")
@app.put("/posts/{post_id}", response_model=Post)
def update_post(post_id: int, post_update: PostCreate):
for post in posts_db:
if post["id"] == post_id:
post["title"] = post_update.title
post["content"] = post_update.content
post["author"] = post_update.author
post["tags"] = post_update.tags
post["updated_at"] = datetime.now()
return post
raise HTTPException(status_code=404, detail="Post not found")
@app.delete("/posts/{post_id}")
def delete_post(post_id: int):
for i, post in enumerate(posts_db):
if post["id"] == post_id:
posts_db.pop(i)
return {"message": "Post deleted successfully"}
raise HTTPException(status_code=404, detail="Post not found")
Understanding the Code
Let’s break down the key components of our API.
Pydantic Models: We use Pydantic models for data validation and serialization. The PostBase model defines the common fields, while PostCreate is used for incoming data and Post includes additional fields like ID and timestamps. FastAPI automatically validates incoming requests against these models and returns helpful error messages if validation fails.
Path Operations: Each function decorated with @app.get(), @app.post(), etc., defines an API endpoint. FastAPI uses Python type hints to automatically validate and convert path parameters, query parameters, and request bodies.
Response Models: The response_model parameter ensures that the returned data matches the specified Pydantic model. This provides both runtime validation and automatic API documentation.
HTTP Status Codes: We use appropriate status codes like 201 for successful creation and 404 for not found errors. FastAPI makes it easy to customize these with the status_code parameter.
Running Your API
Start the development server with Uvicorn:
uvicorn main:app --reload
The --reload flag enables auto-reloading when you modify your code, which is perfect for development.
Testing Your API
Once your server is running, navigate to http://127.0.0.1:8000/docs in your browser. You’ll see an automatically generated, interactive API documentation page. This is one of FastAPI’s killer features. You can test all your endpoints directly from this interface without writing a single line of documentation code.
Let’s test creating a post using curl:
curl -X POST "http://127.0.0.1:8000/posts/" \
-H "Content-Type: application/json" \
-d '{
"title": "Getting Started with FastAPI",
"content": "FastAPI is an amazing framework for building APIs in Python.",
"author": "Jane Developer",
"tags": ["python", "fastapi", "tutorial"]
}'
Retrieve all posts:
curl "http://127.0.0.1:8000/posts/"
Adding Query Parameters and Filtering
Let’s enhance our API with search functionality. Add this new endpoint to your code:
@app.get("/posts/search/", response_model=List[Post])
def search_posts(q: Optional[str] = None, tag: Optional[str] = None):
results = posts_db
if q:
results = [post for post in results
if q.lower() in post["title"].lower()
or q.lower() in post["content"].lower()]
if tag:
results = [post for post in results
if tag in post["tags"]]
return results
This endpoint allows users to search posts by keyword or filter by tag. FastAPI automatically documents these optional query parameters.
Error Handling and Validation
FastAPI provides excellent error handling out of the box. When validation fails, it returns detailed error messages:
curl -X POST "http://127.0.0.1:8000/posts/" \
-H "Content-Type: application/json" \
-d '{"title": "Missing Fields"}'
This will return a 422 Unprocessable Entity response with details about which fields are missing and what types are expected.
Next Steps and Best Practices
While our example uses an in-memory database, a production application should use a proper database. FastAPI works excellently with SQLAlchemy for SQL databases or motor for MongoDB. Consider adding authentication using OAuth2 with JWT tokens, which FastAPI supports through its security utilities.
Implement proper logging using Python’s logging module to track API usage and errors. Add CORS middleware if your API will be accessed from web browsers. Use environment variables for configuration rather than hardcoding values.
Consider adding rate limiting to prevent abuse, implement pagination for large datasets, and add comprehensive tests using pytest and FastAPI’s TestClient.
Performance Considerations
FastAPI’s async capabilities allow it to handle thousands of concurrent connections efficiently. To take full advantage, use async database drivers like asyncpg for PostgreSQL or motor for MongoDB:
@app.get("/posts/{post_id}")
async def get_post(post_id: int):
# Async database call would go here
pass
The async/await syntax integrates seamlessly with FastAPI’s architecture, allowing you to build high-performance APIs that can handle significant load.
Conclusion
FastAPI provides a modern, fast, and enjoyable way to build APIs in Python. Its automatic documentation, type safety, and excellent performance make it an ideal choice for projects ranging from small microservices to large-scale applications. The framework’s design encourages best practices while remaining flexible enough to adapt to your specific needs.
Start small, follow the patterns we’ve explored here, and gradually add more sophisticated features as your application grows. The FastAPI documentation is excellent and covers advanced topics like background tasks, WebSocket support, and custom middleware. Happy coding!