What does the decorator actually do?

It registers the function in the app's routing table under a path and HTTP method. The function itself is returned unchanged.

Why does my endpoint return JSON when I return a dict?

FastAPI serializes the return value with its JSON encoder and sets the content type to application/json.

Why can't I reach a route I declared later in the file?

Routes match in registration order and the first match wins. Put fixed paths before paths with parameters that would shadow them.

How do I change the default status code?

Pass status_code to the decorator, for example @app.post("/items", status_code=201).

How do I run the app?

Run uvicorn main:app --reload, where main is the file name and app is the FastAPI instance. The --reload flag is for development only.

Where does the description in /docs come from?

From the function's docstring, unless you pass description to the decorator. Markdown in the docstring is rendered.

Your First Endpoint

FastAPIBy Ashish JangraUpdated 15 October 2026

What the decorator does, what the return value becomes, and how a function turns into a route.

Overview

The decorator does not wrap anything

An endpoint is a Python function that answers one kind of request at one address. You write the function, add a decorator that names the method and the path, and FastAPI does the rest. The first one is the smallest useful program you can write with the framework, and it teaches more than its size suggests.

The decorator looks like it wraps your function, but it does not. It registers the function in a table of routes and hands the function back untouched. That is why you can still call it directly in a test. Once you see this, a lot of behavior stops feeling like magic.

This article walks through what happens to the value you return and how it becomes JSON. It then covers status codes and why the default is rarely the right one for creation. After that it explains route order, the rule that decides which handler wins when two paths could match the same URL. It closes with how to describe what you built so the generated docs make sense, and a short note on designing paths that age well.

If you only read one thing here, read the part on route order. It is the mistake that catches nearly everyone exactly once, and it is easy to avoid once you know it exists.

You do not need any earlier FastAPI experience to follow it. A basic grasp of Python functions is enough, and every idea is introduced as it comes up. Keep a terminal open if you want to try the examples as you read.

@app.get("/modules")
def read_modules():
    return [{"title": "Vectors"}]

The instinct is that @app.get wraps the function in a thing. It doesn't. It registers it. The app records the path, the HTTP method and the function's signature in a routing table, and returns the function unchanged.

You can verify that, and the first editor above does. read_modules() called right still returns the list. This is worth knowing because it means an endpoint is an plain function, testable on its own, with no framework machinery attached to it.

What the app records from the signature is more than the name. It notes which params match to placeholders in the path. This Have defaults. What each is annotated as. That analysis happens once, at import. This Is why routing is cheap at request time.

Worth knowing

The decorator registers a route; it does not wrap your function. Calling the function directly still works exactly as before.

Whatever you return is serialised to JSON — dicts, lists, models and primitives all work. The default status is 200.

status_code= on the decorator sets that route's default. The status module gives every code a readable name.

Routes match in registration order, so /modules/latest must be declared before /modules/{id} or it will never be reached.

summary, tags and the function's docstring all flow into the OpenAPI document and the docs page.

A 204 response must have no body. Declare status_code=204 and return None — returning a value with a 204 produces a malformed response.

from fastapi import FastAPI app = FastAPI() @app.get("/modules") def read_modules(): return [{"title": "Vectors"}, {"title": "Norms"}] print("routes registered:") for route in app.routes: methods = getattr(route, "methods", None) if methods: print(" %-8s %s" % (",".join(sorted(methods)), route.path)) print() print("the function is untouched:", read_modules())

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class Module(BaseModel): title: str minutes: int @app.get("/dict") def a(): return {"kind": "dict"} @app.get("/list") def b(): return [1, 2, 3] @app.get("/model") def c(): return Module(title="Vectors", minutes=8) @app.get("/scalar") def d(): return "just a string" client = TestClient(app) for path in ["/dict", "/list", "/model", "/scalar"]: r = client.get(path) print("%-8s %s %-14s %s" % (path, r.status_code, r.headers.get("content-type"), r.text))

from fastapi import FastAPI, status app = FastAPI() @app.post("/modules", status_code=status.HTTP_201_CREATED) def create(): return {"created": True} @app.delete("/modules/{i}", status_code=status.HTTP_204_NO_CONTENT) def delete(i: int): return None # 204 means "nothing to say" client = TestClient(app) r1 = client.post("/modules") r2 = client.delete("/modules/1") print("create :", r1.status_code, r1.json()) print("delete :", r2.status_code, repr(r2.text), "<- 204 has no body")

from fastapi import FastAPI wrong = FastAPI() @wrong.get("/modules/{module_id}") def by_id(module_id: str): return {"matched": "by_id", "value": module_id} @wrong.get("/modules/latest") # registered second - never reached def latest_wrong(): return {"matched": "latest"} right = FastAPI() @right.get("/modules/latest") # fixed path first def latest_right(): return {"matched": "latest"} @right.get("/modules/{module_id}") def by_id2(module_id: str): return {"matched": "by_id", "value": module_id} print("wrong order:", TestClient(wrong).get("/modules/latest").json()) print("right order:", TestClient(right).get("/modules/latest").json()) print("still works:", TestClient(right).get("/modules/7").json())

import json from fastapi import FastAPI app = FastAPI() @app.get("/modules", summary="List modules", tags=["modules"]) def read_modules(): """Return every published module, newest first. Unpublished drafts are excluded. """ return [] spec = app.openapi()["paths"]["/modules"]["get"] print("summary :", spec["summary"]) print("tags :", spec["tags"]) print("description:") print(spec["description"])

from fastapi import FastAPI, status from pydantic import BaseModel, Field app = FastAPI(title="VizLearn") DB = {1: {"id": 1, "title": "Vectors", "minutes": 8}} class ModuleIn(BaseModel): title: str = Field(min_length=3) minutes: int = Field(default=10, gt=0) @app.get("/modules", tags=["modules"]) def list_modules(): return list(DB.values()) @app.post("/modules", status_code=status.HTTP_201_CREATED, tags=["modules"]) def create_module(module: ModuleIn): new_id = max(DB) + 1 DB[new_id] = {"id": new_id, **module.model_dump()} return DB[new_id] client = TestClient(app) print("before :", client.get("/modules").json()) r = client.post("/modules", json={"title": "Eigenvalues", "minutes": 14}) print("created:", r.status_code, r.json()) print("after :", client.get("/modules").json())

@app.post("/modules", response_model=ModuleOut, status_code=status.HTTP_201_CREATED, tags=["modules"]) def create_module(module: ModuleCreate) -> ModuleOut: """Create a module and return it with its assigned id.""" return service.create_module(module)

About the author

Ashish Jangra builds and maintains VizLearn. Every module here is written and the visualisation behind it hand-built, so the numbers in a readout come from the same code that draws the picture. Corrections are genuinely welcome and get priority over everything else — if a page states something wrong, or an animation misrepresents what the algorithm does, get in touch.

Your First Endpoint

Overview

The decorator does not wrap anything

Worth knowing