Skip to content

Beginner FastAPI Tutorial with Poetry

This tutorial guides you through creating your first FastAPI project using Poetry, a modern dependency and packaging tool for Python.

1. What You’ll Build

You’ll create a basic FastAPI application with a single endpoint that returns a JSON response. We'll manage dependencies with Poetry and utilize features like FastAPI's interactive documentation.

2. Prerequisites

  • Python 3.7 or higher installed on your system.
  • Poetry installed. You can install it using the command: 
    curl -sSL https://install.python-poetry.org | python3 -

3. Setting Up the Project

Step 1: Create a New Poetry Project

Run the following command to create a new project:

poetry new fastapi-tutorial

This will generate a project structure:

fastapi-tutorial/
├── fastapi_tutorial/
│   ├── __init__.py
├── tests/
│   ├── __init__.py
├── pyproject.toml

Step 2: Add Dependencies

Navigate to the project directory and add FastAPI and Uvicorn:

cd fastapi-tutorial
poetry add fastapi uvicorn

4. Writing Your First FastAPI Application

Step 1: Create the Main Application File

Inside the fastapi_tutorial/ folder, create a file named main.py:

touch fastapi_tutorial/main.py

Add the following code to main.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Welcome to your first FastAPI app!"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

5. Running Your Application

Step 1: Start the Server

Run the server using Uvicorn:

poetry run uvicorn fastapi_tutorial.main:app --reload

Step 2: Access Your API

6. Testing Your API

Step 1: Add a Test

Inside the tests/ folder, create a file named test_main.py:

touch tests/test_main.py

Add the following code to test_main.py:

from fastapi.testclient import TestClient
from fastapi_tutorial.main import app

client = TestClient(app)

def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Welcome to your first FastAPI app!"}

def test_read_item():
    response = client.get("/items/42?q=test-query")
    assert response.status_code == 200
    assert response.json() == {"item_id": 42, "q": "test-query"}

Step 2: Run the Tests

Run the tests using Poetry:

poetry run pytest

7. Next Steps

  • Add more endpoints to expand your API.
  • Explore FastAPI’s features like dependency injection, authentication, and database integration.
  • Deploy your application to the cloud using platforms like AWS, Heroku, or DigitalOcean.

Wrapping Up

You’ve now built your first FastAPI application using Poetry for dependency and project management. You’ve learned how to set up a FastAPI project, create endpoints, and test your application. This foundation prepares you to explore more advanced features like authentication, database integration, and API versioning.

For a more complete, production-ready boilerplate that includes advanced features like authentication, database integration, and follows industry best practices, check out the Craft Your Startup boilerplate. It’s the perfect way to accelerate your development and launch your startup projects faster!