Vercel Logo

Tour the FastAPI starter

The Hazel Home API has a short job description: return furniture. We'll use uv to set up its Python environment, then run it on its own to see what the storefront will receive. Once we configure Services in Section 2, vercel dev will start both apps for us.

Outcome

Run the FastAPI backend locally and confirm that /api/items returns eight furniture items.

Hands-on exercise 1.2

Get the starter

Clone the repository, then enter its student project:

git clone https://github.com/vercel/academy-python-course.git
cd academy-python-course/starter

The repository contains both starter/ and complete/. We work in starter/; complete/ is the finished reference. Inside each project, backend/ contains FastAPI and frontend/ contains Next.js.

Install the backend

We'll use uv to manage Python and the backend dependencies. Follow the installation instructions for your operating system, reopen your terminal if prompted, and check that uv --version prints a version number.

From starter/, install the dependencies with Python 3.12:

cd backend
uv sync --python 3.12
uv run python --version

uv sync creates backend/.venv, installs the dependencies from pyproject.toml, and writes backend/uv.lock. It can download Python 3.12 if it isn't installed. uv run uses that environment automatically, so these commands work on macOS, Linux, and Windows without an activation step.

The dependency file declares fastapi[standard]. The standard extra includes the development CLI and server. For this first tour, start FastAPI from starter/backend/:

uv run fastapi dev main.py

Open http://localhost:8000/api/items to see the inventory. FastAPI's interactive API docs are at http://localhost:8000/docs.

Read the application

Open backend/main.py from the student project root. Its routes return the store name and inventory:

from fastapi import FastAPI
 
app = FastAPI()
 
# The starter includes the full furniture list above these routes.
@app.get("/api")
def home():
    return {"message": "Hazel Home Furniture API"}
 
@app.get("/api/items")
def get_items():
    return items

The application is named app. In Section 2, we'll configure its Services entrypoint as main:app: the main.py module and its app object. The /api prefix is part of our URL design. The backend lives in backend/, and an explicit rewrite will direct public API requests to it.

Check the dependency file

Open backend/pyproject.toml:

[project]
name = "hazel-home"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]>=0.141.1",
]

Vercel installs these dependencies for the backend service. It currently supports Python 3.12, 3.13, and 3.14, with 3.12 as the default. The starter keeps a 3.12 minimum; that requirement does not pin local and deployed interpreters to the same minor version.

Our uv sync --python 3.12 command selects the same minor as Vercel's current default. To target Python 3.14, change requires-python to ">=3.14,<3.15" in backend/pyproject.toml, then run uv sync --python 3.14. The Python version guide explains deployment selection. Vercel supports the uv.lock file alongside pyproject.toml.

Try It

Leave FastAPI running. In another terminal, request both endpoints:

curl http://localhost:8000/api
curl http://localhost:8000/api/items

The first returns {"message":"Hazel Home Furniture API"}. The second returns eight items, starting with Fernwood Sectional. Check that each item includes id, name, category, price, and in_stock.

Commit

Save the generated lockfile from starter/ so other installs use the same dependency versions:

git add backend/uv.lock
git commit -m "chore(backend): lock Python dependencies with uv"

Git ignores .venv/. If the lockfile is already committed and unchanged, there is nothing new to commit.

Troubleshooting

main.py is missing: Check your working directory. The backend is at academy-python-course/starter/backend/main.py, one level below the student project.

uv is not found: Complete the uv installation and reopen your terminal so it picks up the updated PATH.

fastapi is not found: Run uv sync --python 3.12 from backend/, then use uv run fastapi dev main.py. The dependency must include [standard] for the CLI.

Installation says Python is unsupported: Check requires-python in backend/pyproject.toml and select a matching supported version with uv sync --python 3.12 (or 3.14 if you changed the requirement). Confirm it with uv run python --version.

Port 8000 is busy: Stop the process using it, or run uv run fastapi dev main.py --port 8001 and use that port for these checks.

Done-When

  • backend/uv.lock exists and uv run python --version shows the selected supported version
  • uv run fastapi dev main.py starts from starter/backend/
  • /api/items returns all eight furniture items
  • You can identify app in backend/main.py and the dependency in backend/pyproject.toml

Solution

The supplied backend is already complete. From the repository root, run:

cd starter/backend
uv sync --python 3.12
uv run python --version
uv run fastapi dev main.py

Keep this terminal open for the next lesson. We'll start the frontend in a second terminal.

Was this helpful?

supported.