This content originally appeared on DEV Community and was authored by James
Building a Todo API with FastAPI: Step-by-Step Guide
Code can be found here: GitHub - jamesbmour/blog_tutorials:
I. Introduction
In the previous post, we introduced FastAPI and set up a basic project structure. Now, we’ll take it a step further by building a functional Todo API. By the end of this tutorial, you’ll have a working backend that can create, read, update, and delete todo items.
What We’ll Cover:
- Designing the Todo Data Model
- Implementing CRUD Operations
- Creating API Endpoints
- Adding Input Validation and Error Handling
- Testing the API
- Refactoring and Organizing Code
II. Designing the Todo Data Model
To manage todos, we must define a data model representing a todo item. FastAPI uses Pydantic models to validate and parse data, so we’ll leverage that here.
A. Defining the Todo Schema
We’ll create two models using Pydantic:
- TodoCreate: For input data when creating or updating a todo.
-
Todo: For the complete todo item, including fields like
idandcreated_at.
from pydantic import BaseModel
from typing import Optional
from datetime import datetime
class TodoCreate(BaseModel):
title: str
description: Optional[str] = None
completed: bool = False
class Todo(BaseModel):
id: str
title: str
description: Optional[str] = None
completed: bool
created_at: datetime
B. Explaining the Fields
- id: Unique identifier for each todo.
- title: Main content of the todo.
- description: Additional details (optional).
- completed: Boolean status of the todo (whether it's done or not).
- created_at: Timestamp indicating when the todo was created.
III. Creating CRUD Operations for Todos
CRUD stands for Create, Read, Update, and Delete—the four basic operations for managing data. We’ll implement these operations using an in-memory database (a simple list) for this tutorial.
A. Setting Up an In-Memory Database
We’ll use a list to store our todos. For simplicity, we’ll also add a few example todos.
from uuid import uuid4
from datetime import datetime
todos = [
{
"id": str(uuid4()),
"title": "Learn FastAPI",
"description": "Go through the official FastAPI documentation and tutorials.",
"completed": False,
"created_at": datetime.now(),
},
{
"id": str(uuid4()),
"title": "Build a Todo API",
"description": "Create a REST API for managing todo items using FastAPI.",
"completed": False,
"created_at": datetime.now(),
},
{
"id": str(uuid4()),
"title": "Write blog post",
"description": "Draft a blog post about creating a Todo API with FastAPI.",
"completed": False,
"created_at": datetime.now(),
},
]
B. Implementing Helper Functions
We’ll implement a simple helper function to find a todo by its id.
def get_todo_by_id(todo_id: str):
for todo in todos:
if todo["id"] == todo_id:
return todo
return None
IV. Implementing API Endpoints
A. Creating a New Todo
The POST endpoint allows users to create a new todo item.
@app.post("/todos/", response_model=Todo)
def create_todo(todo: TodoCreate):
new_todo = Todo(
id=str(uuid4()),
title=todo.title,
description=todo.description,
completed=todo.completed,
created_at=datetime.now()
)
todos.append(new_todo.dict())
return new_todo
B. Retrieving All Todos
The GET endpoint retrieves all todos from our in-memory database.
@app.get("/todos/", response_model=List[Todo])
def get_all_todos():
return todos
C. Retrieving a Single Todo
The GET endpoint allows retrieving a single todo by its id.
@app.get("/todos/{todo_id}", response_model=Todo)
def get_todo(todo_id: str):
todo = get_todo_by_id(todo_id)
if not todo:
raise HTTPException(status_code=404, detail="Todo not found")
return todo
D. Updating a Todo
The PUT endpoint allows users to update an existing todo.
@app.put("/todos/{todo_id}", response_model=Todo)
def update_todo(todo_id: str, todo_data: TodoCreate):
todo = get_todo_by_id(todo_id)
if not todo:
raise HTTPException(status_code=404, detail="Todo not found")
todo["title"] = todo_data.title
todo["description"] = todo_data.description
todo["completed"] = todo_data.completed
return Todo(**todo)
E. Deleting a Todo
The DELETE endpoint allows users to delete a todo by its id.
@app.delete("/todos/{todo_id}")
def delete_todo(todo_id: str):
todo = get_todo_by_id(todo_id)
if not todo:
raise HTTPException(status_code=404, detail="Todo not found")
todos.remove(todo)
return {"detail": "Todo deleted successfully"}
V. Adding Input Validation and Error Handling
A. Input Validation with Pydantic
FastAPI automatically validates input data against the Pydantic models we defined. This ensures that the data meets our expected schema before it’s processed.
B. Custom Error Handling
We can customize error responses by adding an exception handler.
@app.exception_handler(HTTPException)
def http_exception_handler(request, exc: HTTPException):
return JSONResponse(
status_code=exc.status_code,
content={"detail": exc.detail},
)
VI. Testing the API
FastAPI comes with interactive Swagger UI documentation, making it easy to test your API endpoints. Simply run the application and navigate to /docs in your browser.
Testing Example
- Create a Todo: Test the POST endpoint by creating a new todo.
-
Retrieve Todos: Use the GET endpoints to fetch all todos or a specific one by
id. - Update and Delete: Test the PUT and DELETE endpoints to update or remove a todo.
VII. Refactoring and Organizing Code
As the application grows, it’s essential to keep the code organized. Here are a few tips:
A. Moving Models to a Separate File
You can move your Pydantic models to a models.py file to keep your main application file clean.
B. Creating a Router for Todo Endpoints
Consider creating a separate router for todo-related endpoints, especially as your API grows.
VIII. Next Steps
In the next post, we’ll integrate a real database (like SQLite or PostgreSQL) into our FastAPI application. We’ll also look into user authentication and more advanced features.
Suggested Improvements:
- Add filtering and pagination to the GET endpoints.
- Implement user authentication to manage personal todos.
IX. Conclusion
In this tutorial, we built a simple Todo API using FastAPI. We started by designing a data model, implemented CRUD operations, and created endpoints to manage todos. We also touched on input validation, error handling, and testing. With this foundation, you can extend the API further or integrate it with a frontend to create a full-fledged application.
If you would like to support my writing or buy me a beer:
https://buymeacoffee.com/bmours
This content originally appeared on DEV Community and was authored by James
James | Sciencx (2024-08-27T14:54:03+00:00) Part 2: Building a Todo API with FastAPI: Step-by-Step Guide. Retrieved from https://www.scien.cx/2024/08/27/part-2-building-a-todo-api-with-fastapi-step-by-step-guide/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.