Cum setezi codurile de status și antetele?

Question

Accepted Answer

FastAPI returnează `200 OK` implicit, dar tu controlezi **codul de status** (prin decorator sau obiectul response) și **antetele** când ai nevoie de un comportament diferit — important pentru semantica REST corectă.

## Setarea unui cod de status implicit pe rută

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 for resource creation
def create_item(item: Item):
    return item                                             # returns with 201

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)  # 204
def delete_item(id: int):
    ...
```

Parametrul decorator `status_code` setează statusul de succes implicit. Folosirea constantelor `status` (de exemplu, `status.HTTP_201_CREATED`) este mai clară decât numerele magice. Codurile corecte conteaza: `201` pentru creat, `204` pentru fără conținut, etc.

## Coduri de status dinamice și antete prin obiectul Response

```python
from fastapi import Response

@app.get("/items/{id}")
def get_item(id: int, response: Response):
    item = db.get(id)
    if not item:
        response.status_code = status.HTTP_404_NOT_FOUND   # set dynamically
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # set a custom header
    return item
```

Injectarea unui parametru `Response` te permite să setezi codul de status și antetele **condiționat** în timp de execuție.

## De ce conteaza

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found",
                            headers={"X-Error": "NotFound"})   # status + detail + headers
    return item
```

Pentru răspunsuri de eroare, `raise HTTPException(...)` este modul idiomantic — setează statusul, un mesaj JSON `detail` și antete opționale.

## Returnarea unui Response personalizat direct

```python
from fastapi.responses import JSONResponse
return JSONResponse(content={...}, status_code=202, headers={"X-Custom": "v"})
```

Codurile de status și antetele corecte sunt esențiale pentru a construi API-uri REST corecte și bine-comportate — clienții și instrumentele se bazează pe semantica HTTP standard (201 pentru creat, 404 pentru nu s-a găsit, 204 pentru fără conținut, etc.), deci returnarea codului corect face parte din contractul unei API-uri de calitate.

FastAPI îți oferă control pur și simplu: un `status_code` implicit pe rută pentru cazul obișnuit, obiectul `Response` injectabil pentru coduri/antete dinamice și `HTTPException` ca modul idiomantic de a semnala erori cu statusul corespunzător și detalii JSON.

Înțelegerea acestor mecanisme — și utilizarea constantelor `status` pentru claritate — este cunoștință zilnică pentru construirea API-urilor care funcționează corect și comunică clar cu consumatorii lor.

Setarea unui cod de status implicit pe rută

Coduri de status dinamice și antete prin obiectul Response

De ce conteaza

Returnarea unui Response personalizat direct

question.related