FastAPI is one of the best frameworks for building modern APIs with Python. It combines clean syntax, automatic validation, interactive documentation, async support, and excellent developer experience. If you already know the basics of Python and want to create backend services, REST APIs, internal tools, or microservices, FastAPI gives you a fast path from idea to production-ready code.
This English version is not a literal translation of the Portuguese post. It is adapted for developers searching for a clear, practical FastAPI guide. You will learn what FastAPI is, why it is popular, how it compares to Flask, how to create routes, validate request data with Pydantic, return JSON responses, organize a small project, and prepare the API for real-world deployment. If you are still building your Python foundation, start with this Python beginner guide before jumping into APIs.
What Is FastAPI?
FastAPI is a Python web framework designed for building APIs quickly and safely. It uses standard Python type hints to validate input, serialize output, generate OpenAPI documentation, and improve editor support. That means your function signatures do more than document your intent. They become part of the API contract. The official FastAPI documentation explains the framework around speed, automatic docs, and modern Python features.
Unlike older frameworks where you manually validate request payloads, parse JSON, and write documentation separately, FastAPI automates many of those steps. You define models, write route functions, and the framework handles a large amount of repetitive backend work. That is especially useful for APIs because correctness and consistency matter. If a client sends a string where your API expects an integer, FastAPI can reject the request before your business logic runs.
Why Developers Choose FastAPI
The first reason developers like FastAPI is productivity. A small API can be created in minutes, but the framework still supports serious features such as dependency injection, async endpoints, authentication, middleware, background tasks, and OpenAPI documentation. You can start small and grow without immediately changing frameworks.
The second reason is validation. FastAPI works closely with Pydantic, a data validation library that uses Python type annotations. Pydantic models make request bodies explicit, readable, and testable. The Pydantic documentation is worth reading if you want to understand model validation, field constraints, serialization, and error messages in more depth.
The third reason is documentation. FastAPI automatically generates interactive documentation for your routes. Once the server is running, you can open /docs in the browser and test endpoints visually. This helps beginners understand what the API expects and helps teams communicate backend behavior without manually maintaining a separate API document.
FastAPI vs Flask
Flask and FastAPI are both excellent Python web tools, but they have different design priorities. Flask is minimal, flexible, and widely used for small web apps, dashboards, and simple APIs. FastAPI is API-first, type-hint-driven, and built for automatic validation and documentation. If you want to understand the simpler Flask style first, read this Flask tutorial.
Choose Flask if you want a lightweight web framework with a very simple mental model. Choose FastAPI if your project is mainly an API and you care about request validation, OpenAPI docs, async support, and structured request/response models. In many modern backend projects, FastAPI is the more convenient option because the API contract becomes part of the code itself.
Set Up a FastAPI Project
Start with a virtual environment. This keeps dependencies isolated and avoids conflicts between projects. It also makes deployment easier because you can reproduce the same package list later. For a full explanation, follow this guide on creating a Python virtual environment with venv.
mkdir fastapi-demo
cd fastapi-demo
python -m venv venv
# Windows
venvScriptsactivate
# macOS or Linux
source venv/bin/activate
pip install fastapi uvicornFastAPI is the framework. Uvicorn is the ASGI server that runs your application. ASGI is the modern Python interface for asynchronous web applications. You do not need to master ASGI immediately, but it helps to know that FastAPI is designed for modern async-friendly web workloads.
Create Your First FastAPI App
Create a file called main.py. The smallest useful FastAPI app defines an application object and one route. A route maps an HTTP method and URL path to a Python function. When the client calls that URL, FastAPI runs the function and returns the response.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello from FastAPI"}Run the server with Uvicorn:
uvicorn main:app --reloadOpen http://127.0.0.1:8000 in your browser. Then open http://127.0.0.1:8000/docs to see the automatic Swagger UI documentation. The --reload option restarts the server when files change, which is useful during development. Do not use auto-reload in production.
Path Parameters and Query Parameters
Most APIs need to receive data from the URL. FastAPI makes this straightforward. A path parameter is part of the URL path, such as /users/42. A query parameter appears after a question mark, such as /users?active=true. Type hints tell FastAPI how to validate and convert values.
@app.get("/users/{user_id}")
def get_user(user_id: int, active: bool = True):
return {
"user_id": user_id,
"active": active
}If someone calls /users/abc, FastAPI knows that user_id should be an integer and returns a validation error. You do not need to manually convert the value with int() inside the function. Understanding Python data types makes this behavior easier to predict.
Request Bodies with Pydantic Models
For POST and PUT requests, APIs often receive JSON bodies. With FastAPI, you define the expected structure using a Pydantic model. The model validates required fields, types, defaults, and constraints. This reduces boilerplate and prevents many common API bugs.
from pydantic import BaseModel, Field
class Product(BaseModel):
name: str = Field(min_length=2, max_length=80)
price: float = Field(gt=0)
in_stock: bool = True
@app.post("/products")
def create_product(product: Product):
return {
"message": "Product created",
"product": product
}If the client sends a negative price or omits a required field, FastAPI returns a structured validation error automatically. This is one of the main advantages of using FastAPI instead of manually checking dictionaries. It keeps route functions focused on business logic instead of repetitive input parsing.
Build a Simple CRUD API
A practical API usually needs CRUD operations: create, read, update, and delete. The following example uses an in-memory dictionary to keep the tutorial simple. In production, you would use a database such as PostgreSQL, MySQL, or SQLite. If you want a lightweight database path, see this guide on Python and SQLite.
from fastapi import HTTPException
products = {}
next_id = 1
@app.post("/items")
def create_item(product: Product):
global next_id
item_id = next_id
products[item_id] = product
next_id += 1
return {"id": item_id, "product": product}
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id not in products:
raise HTTPException(status_code=404, detail="Item not found")
return {"id": item_id, "product": products[item_id]}
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
if item_id not in products:
raise HTTPException(status_code=404, detail="Item not found")
del products[item_id]
return {"message": "Item deleted"}This example is intentionally simple, but it demonstrates the core API structure. Routes receive requests, validate data, run business logic, and return JSON. Once this pattern feels natural, moving from dictionaries to a real database becomes much easier.
Async Routes: When Should You Use Them?
FastAPI supports both regular functions and async functions. Use async def when your route awaits asynchronous operations, such as async database calls, HTTP requests, or other I/O-bound work. Do not use async only because it looks modern. If your code performs CPU-heavy work or calls blocking libraries, async will not magically make it faster.
@app.get("/status")
async def status():
return {"status": "ok"}For CPU-bound tasks, consider background workers, multiprocessing, or optimized libraries. If your API feels slow, measure first. This guide on how to identify bottlenecks with cProfile can help you avoid guessing.
Authentication and Security
APIs often need authentication. FastAPI can support API keys, OAuth2, JWT tokens, cookies, and custom dependencies. The right approach depends on the kind of client consuming your API. A public mobile app, a browser frontend, an internal service, and an admin dashboard may require different security decisions.
A common pattern is to protect routes with JWT access tokens. The implementation details vary, but the idea is the same: the client logs in, receives a signed token, and sends that token with later requests. If you want to understand that model before implementing it in FastAPI, read this guide on how to secure a Flask API with JWT. The concepts transfer well across Python web frameworks.
Never store secrets directly in your source code. Use environment variables or a secret manager for API keys, database URLs, and token signing keys. This article on how to read environment variables in Python is a useful next step before deployment.
Project Structure for a Growing API
A single main.py file is fine for learning, but a real project should be organized. Keep routers, models, services, configuration, and database code separated. This makes the project easier to test and maintain. A small structure might look like this:
app/
├── main.py
├── config.py
├── routers/
│ └── products.py
├── models/
│ └── product.py
└── services/
└── product_service.pyThis structure prevents route files from becoming too large. Routes should handle HTTP concerns. Services should handle business logic. Models should define data structure. Configuration should be centralized. If you understand Python modules and packages, this organization will feel natural.
Testing Your FastAPI App
FastAPI works well with automated tests. You can use a test client to call routes without starting a real server. Test validation errors, successful requests, authentication failures, and edge cases. API tests are especially important because clients depend on stable behavior.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_read_root():
response = client.get("/")
assert response.status_code == 200
assert response.json()["message"] == "Hello from FastAPI"Good tests make refactoring safer. When you add authentication, databases, or background tasks, tests protect you from breaking existing routes. They also document how the API is supposed to behave.
Deployment Tips
Before deploying a FastAPI app, freeze your dependencies, disable reload mode, configure environment variables, add logging, and run the app with a production-ready server setup. Many platforms can host FastAPI, including Render, Railway, Fly.io, AWS, Google Cloud, Azure, and VPS providers. For container-based deployment, this guide on how to run Python with Docker gives you a useful foundation.
You should also think about CORS, rate limiting, database migrations, HTTPS, monitoring, and error tracking. A tutorial API can be simple. A production API must be observable, secure, and predictable. Start with the basics, then improve the architecture as real requirements appear.
Final Checklist
Before calling your FastAPI project complete, verify this checklist: routes are clear, request bodies use Pydantic models, validation errors are handled, secrets are outside the source code, interactive docs work, tests cover important endpoints, database access is organized, authentication is planned, and deployment settings are separated from development settings.
FastAPI is popular because it gives Python developers a modern API workflow without excessive ceremony. You get speed, validation, documentation, type hints, and a clean developer experience in the same framework. If your next project needs a backend API, FastAPI is one of the strongest options in the Python ecosystem.
