FastAPI has officially become the fastest-growing Python web framework in 2026, and for very good reasons. It blends the speed of Node.js and Go with the simplicity of Python, giving you lightning-fast APIs without the complexity. If you are a beginner wondering where to start, this is the perfect guide for you.
In this complete walkthrough, you will learn how to build REST API with FastAPI for beginners from absolute scratch. We will install FastAPI and Uvicorn, build your first routes, validate data with Pydantic models, and explore the magical auto-generated Swagger docs. Every step includes working code you can copy, paste, and run.
By the end of this FastAPI tutorial step by step with examples, you will have a working to-do list API with create, read, and validation features. No prior API experience is needed, just basic Python knowledge and a curiosity to learn. Let us get your first FastAPI app running in under ten minutes.
What Is FastAPI and Why Should You Use It
FastAPI is a modern, high-performance web framework created by Sebastián Ramírez in 2018. It is specifically designed for building APIs using Python type hints, async support, and automatic documentation. It sits on top of two powerful libraries: Starlette for web handling and Pydantic for data validation.
What makes FastAPI stand out is its ability to write less code while getting more features. You get automatic request validation, interactive Swagger UI docs, dependency injection, and async support out of the box. Developers report shipping features 200 to 300 percent faster with 40 percent fewer bugs.
In 2026, FastAPI powers backend APIs at Microsoft, Netflix, Uber, Hugging Face, Shopify, and ByteDance (TikTok). Over 50 percent of Fortune 500 companies now use it in production. You can explore the official framework at fastapi.tiangolo.com, which is itself a showcase of what FastAPI can do.
Prerequisites Before You Start
Before diving in, make sure your setup is ready for FastAPI 0.136.0 and above. You need Python 3.10 or higher, since FastAPI dropped Python 3.9 support in February 2026. Python 3.12 or newer is recommended for the best performance and compatibility.
You should also have a code editor like VS Code or PyCharm installed. Both offer excellent Python and FastAPI support with autocomplete for type hints. Basic familiarity with Python functions, decorators, and dictionaries is helpful but not mandatory.
Check your Python version by running python --version in your terminal. If it shows 3.10 or above, you are ready to go. Otherwise, download the latest Python from python.org before continuing.
Installing FastAPI and Uvicorn the Right Way
Installing FastAPI is just two quick commands. First, create a clean project folder and move into it using your terminal. Then set up a virtual environment so your project dependencies stay isolated from other Python projects on your machine.
# Create and enter your project folder
mkdir fastapi-tutorial
cd fastapi-tutorial
# Create a virtual environment
python -m venv env
# Activate it (macOS/Linux)
source env/bin/activate
# Or on Windows
env\Scripts\activate
Now install FastAPI along with Uvicorn, the ASGI server that actually runs your FastAPI app. The [standard] extra installs helpful production-grade dependencies like uvloop and httptools automatically.
pip install "fastapi[standard]" "uvicorn[standard]"
Once the install finishes, create a new file named main.py in your project folder. This single file is where we will write our entire first FastAPI application. Ready for the fun part?
Building Your First FastAPI Hello World App
Let us write the classic Hello World endpoint to confirm everything works. Open main.py in your editor and paste the code below. It is just six lines, which shows how clean FastAPI syntax really is.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello World from FastAPI"}
To run the server, go back to your terminal and type the command below. The --reload flag tells Uvicorn to restart automatically whenever you save a code change, which is perfect for development.
uvicorn main:app --reload
Now open your browser and visit http://localhost:8000/. You should see the JSON response {"message": "Hello World from FastAPI"}. Congratulations, your first FastAPI app is live and running on your machine.
Understanding Routes and HTTP Methods in FastAPI
Routes define which URLs your app responds to and what happens when users hit them. FastAPI uses Python decorators like @app.get(), @app.post(), @app.put(), and @app.delete() to map functions to URLs. Each method maps to a specific CRUD operation.
GET retrieves data, POST creates new data, PUT replaces data, PATCH updates partial data, and DELETE removes data. These are the standard REST conventions used across every modern API. FastAPI makes using them feel natural and readable.
Let us build something real now. We will create a tiny to-do list API where you can add new items and fetch them back. This is a classic beginner project that teaches real-world patterns used in production apps.
Creating a POST Route to Add Items
First, define an empty Python list at the top of your file to store to-do items temporarily. In a real app, this would be a database, but for learning purposes in-memory storage works perfectly. We will expand this later.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(item: str):
items.append(item)
return {"items": items}
This simple POST endpoint accepts a query parameter called item, appends it to the list, and returns the updated items. Notice how FastAPI automatically recognizes item: str as a required query parameter thanks to Python type hints.
You can test this endpoint using curl in your terminal as shown below. Each call adds a new item and returns the current list. This is a great first taste of how elegant FastAPI feels in practice.
curl -X POST "http://localhost:8000/items?item=apple"
curl -X POST "http://localhost:8000/items?item=banana"
Using Path Parameters to Fetch Specific Items
Now let us add a GET route that fetches one specific item using its index. This uses path parameters, which live inside the URL path rather than as query strings. The syntax is curly braces around the parameter name.
from fastapi import FastAPI, HTTPException
@app.get("/items/{item_id}")
def get_item(item_id: int):
if item_id < 0 or item_id >= len(items):
raise HTTPException(status_code=404, detail="Item not found")
return {"item": items[item_id]}
Notice item_id: int tells FastAPI to automatically convert and validate the URL value as an integer. If a user passes a non-integer like /items/abc, FastAPI returns a clean 422 error automatically. You never have to write validation code yourself.
Try visiting http://localhost:8000/items/0 in your browser after adding a few items. You should see the first item returned in JSON format. This is the core pattern behind nearly every REST API you will ever build.
Handling Errors Gracefully with HTTPException
Default server crashes are ugly and unhelpful for API clients. FastAPI gives you HTTPException to throw clean, descriptive errors with specific status codes. This small touch dramatically improves the developer experience for anyone using your API.
In the previous example, requesting an invalid index triggers a 404 Not Found error with a clear message. You can use any HTTP status code like 400 for bad input, 401 for unauthorized, 403 for forbidden, or 500 for server errors.
from fastapi import HTTPException
if not user_has_permission:
raise HTTPException(
status_code=403,
detail="You do not have permission to access this resource"
)
Descriptive errors save hours of debugging for both you and the frontend team. Make it a habit to throw meaningful errors in every endpoint, even during early development. Your future self will thank you big time.
Query Parameters with Automatic Type Conversion
Query parameters are the key-value pairs that appear after the question mark in a URL. FastAPI parses them automatically and converts them to your declared Python types. No manual parsing code needed, ever.
@app.get("/list_items")
def list_items(limit: int = 10):
return {"items": items[:limit]}
Here, limit defaults to 10, making it optional. Visiting /list_items returns the first 10 items, while /list_items?limit=3 returns just 3. Try it in your browser, it is instant and satisfying.
You can chain multiple query parameters easily, like /search?q=apple&limit=5&sort=desc. Each one gets its own parameter in your function, and FastAPI handles validation automatically. This is where type hints truly start paying off.
Modeling Data with Pydantic for Real APIs
Accepting just a string is fine for demos, but real APIs handle structured data. This is where Pydantic shines brightest. Pydantic lets you define data models using Python classes, and FastAPI automatically validates incoming JSON against them.
from pydantic import BaseModel
class Item(BaseModel):
text: str
is_done: bool = False
priority: int = 1
Now update your POST endpoint to accept an Item object from the JSON request body. FastAPI automatically parses the JSON, validates each field, and rejects bad data with detailed error messages. Developers call this the "magic" of FastAPI.
@app.post("/items")
def create_item(item: Item):
items.append(item)
return {"created": item}
If someone sends invalid JSON like missing the text field or passing a non-integer priority, FastAPI rejects it with a clear 422 error. You get bulletproof input validation without writing a single line of validation code. This is huge.
Defining Response Models for Clean APIs
Just like you validate incoming data, you can enforce what goes back to clients. This is done using the response_model parameter in your route decorator. It guarantees every response follows the exact shape you promise in your docs.
@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int):
if item_id < 0 or item_id >= len(items):
raise HTTPException(status_code=404, detail="Item not found")
return items[item_id]
Response models also automatically filter out extra fields you might accidentally return, keeping sensitive data like passwords safe. Frontend developers love this because they always know exactly what JSON shape to expect. It removes guesswork completely.
Pydantic v2 (used by default in FastAPI 2026) is up to 50 times faster than Pydantic v1, meaning validation happens almost instantly. This is part of why FastAPI handles 15,000+ requests per second in real benchmarks. Speed is built in at every layer.
Interactive API Documentation: The FastAPI Superpower
Here is where FastAPI feels like magic. Without writing a single line of documentation, you get a complete interactive API explorer. Just visit http://localhost:8000/docs while your server is running.
This is Swagger UI, and it lists every endpoint, the required parameters, response models, and example payloads. You can literally click a button, fill in a form, and test any route right from your browser. No Postman or curl needed.
FastAPI also provides an alternative docs style at http://localhost:8000/redoc, which is cleaner for reading and sharing with external clients. Both are generated automatically from your type hints and Pydantic models. Frontend devs, QA testers, and even non-technical stakeholders can explore your API instantly.
Under the hood, both docs UIs are built from an OpenAPI schema that FastAPI generates automatically. You can access it at /openapi.json to integrate with tools like Postman, Insomnia, or Stoplight. This standard compatibility is a massive time-saver in team environments.
Making Endpoints Async for High Performance
FastAPI truly shines with asynchronous endpoints, especially for I/O-heavy work like database queries, external API calls, or file reads. Just add the async keyword before def and FastAPI handles the rest with its ASGI architecture.
import httpx
from fastapi import FastAPI
app = FastAPI()
@app.get("/weather/{city}")
async def get_weather(city: str):
async with httpx.AsyncClient() as client:
response = await client.get(
f"https://api.weather.com/{city}"
)
return response.json()
This async endpoint can serve thousands of concurrent requests without blocking. While one request waits for the weather API to respond, FastAPI handles other requests in parallel. This is exactly why FastAPI dominates AI, ML, and LLM backend services in 2026.
Not everything needs to be async. Keep simple CPU-bound functions as regular def functions. Use async def only when you actually call something that awaits, like database queries or HTTP requests. Mixing them correctly is the secret to great FastAPI code.
Complete Working Example: Your First Mini To-Do API
Let us put everything together into one clean file. Copy this entire code block into main.py, save, and test it in your browser at /docs. This is a real production-ready pattern.
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
app = FastAPI(title="Mini Todo API", version="1.0.0")
class Todo(BaseModel):
text: str
is_done: bool = False
todos: List[Todo] = []
@app.get("/")
def home():
return {"message": "Welcome to Mini Todo API"}
@app.post("/todos", response_model=Todo)
def create_todo(todo: Todo):
todos.append(todo)
return todo
@app.get("/todos", response_model=List[Todo])
def list_todos(limit: int = 10):
return todos[:limit]
@app.get("/todos/{todo_id}", response_model=Todo)
def get_todo(todo_id: int):
if todo_id < 0 or todo_id >= len(todos):
raise HTTPException(404, "Todo not found")
return todos[todo_id]
Run the server with uvicorn main:app --reload and head over to http://localhost:8000/docs. You can add new todos, list them, and fetch by ID, all from the Swagger interface. This little API already demonstrates every core FastAPI pattern you will use daily.
FastAPI vs Flask vs Django: Quick Takeaway
Compared to Flask, FastAPI gives you automatic validation, async support, and auto-docs without extensions. Flask remains great for tiny scripts, but FastAPI wins hands-down for real APIs in 2026. You write less code and get more features.
Compared to Django, FastAPI is lighter, faster, and API-focused. Django remains the king for full web apps with admin panels, ORMs, and user management. For pure API work, FastAPI is the obvious modern choice, especially for microservices and ML backends.
For a deeper comparison, check out our detailed guide on Flask vs Django vs FastAPI on FreeAPIHub.com. It covers real benchmarks, company examples, and when to pick each one.
Pro Tips for FastAPI Beginners
Always use type hints everywhere, even when they feel optional. FastAPI relies on them for validation, documentation, and editor autocomplete. Skipping type hints kills half the framework's magic, which is a rookie mistake.
Organize growing projects with routers instead of dumping everything in main.py. The APIRouter class lets you split endpoints by feature like users.py, orders.py, and products.py. This keeps large codebases clean and navigable.
Use environment variables for secrets and configuration via pydantic-settings. Never hardcode API keys or database URLs directly in code. This is a production-grade habit worth building from day one, even in tutorials.
What to Learn Next After This Tutorial
Now that you have the fundamentals, level up by exploring database integration with SQLAlchemy 2.0 async or SQLModel. Both pair beautifully with FastAPI and give you real persistence beyond in-memory lists. PostgreSQL with asyncpg is the gold-standard combo in 2026.
Next, dive into authentication with JWT tokens or OAuth2 flows. FastAPI's security utilities make this surprisingly pleasant compared to most frameworks. After that, explore background tasks, WebSockets, and testing with pytest and httpx.
Finally, practice deployment with Docker and cloud platforms like AWS, Render, or the new FastAPI Cloud one-command deploy service. Shipping real projects is how you truly master any framework. Build, break, ship, repeat.
Conclusion: Your FastAPI Journey Starts Now
FastAPI proves that Python APIs can be fast, elegant, and developer-friendly at the same time. You learned how to install FastAPI and Uvicorn, build routes, validate data with Pydantic, handle errors, and explore Swagger docs, all in one sitting. That is genuinely impressive progress.
The real magic of FastAPI is how little code you need for so many features. Automatic validation, interactive docs, type-safe responses, and async support come built in. This is why top companies like Netflix, Uber, and Microsoft bet on it for their modern backends.
Keep experimenting, break things, read the excellent official docs, and build small projects. At FreeAPIHub.com, we believe the best way to master FastAPI is through hands-on practice with real APIs. Your journey into high-performance Python API development has officially begun, so go build something amazing.
