Cum definiți rutele (operații de cale)?

Question

Accepted Answer

În FastAPI, o **operație de cale** este o rută — o funcție decorată cu un decorator de metodă HTTP (`@app.get`, `@app.post`, etc.) care gestionează cererile către o cale. Valoarea returnată a funcției este serializată automat la JSON.

## Definirea rutelor pentru fiecare metodă HTTP

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

Fiecare decorator mapează o metodă HTTP + cale la un handler. Numele funcției este al dvs.; decoratorul definește ruta. Dicturile/listele/modelele Pydantic returnate sunt serializate automat la JSON — fără `json.dumps` manual.

## Ordinea contează pentru căile suprapuse

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI potrivește rutele în ordinea declarației, deci plasați căile statice înaintea celor dinamice.

## Metadate de operație (alimentează documentația)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

Parametrii decoratorului (`tags`, `summary`, `status_code`, `response_model`) configurează comportamentul și îmbogățesc documentația generată automat.

## De ce este important

Operațiile de cale sunt fundamentul fiecărei aplicații FastAPI — ele definesc punctele finale ale API-ului dvs. și modul în care se gestionează cererile.

Înțelegerea modelului decorator-per-HTTP-method, faptul că valorile returnate sunt serializate automat la JSON (fără boilerplate), că indiciile de tip pe parametri conduc conversia și validarea, și că ordinea rutelor contează pentru căile suprapuse este cunoaștere esențială de zi cu zi pentru construirea oricărui endpoint.

Metadatele decoratorului alimentează de asemenea documentația automată a FastAPI, conectând rutele direct la documentație.

Acesta este primul și cel mai fundamental lucru de stăpânit în FastAPI.