Hogyan állítod be az állapotkódokat és fejléceket?

Question

Accepted Answer

A FastAPI alapértelmezésben `200 OK` értéket ad vissza, de te szabályozod az **állapotkódot** (a dekorátor vagy a válasz objektum segítségével) és a **fejléceket**, amikor eltérő viselkedésre van szükség — fontos a megfelelő REST szemantika számára.

## Az alapértelmezett állapotkód beállítása az útvonalon

```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):
    ...
```

A dekorátor `status_code` paramétere beállítja az alapértelmezett siker állapotot. Az `status` konstansok (például `status.HTTP_201_CREATED`) használata világosabb, mint a varázsszámok. A helyes kódok fontosak: `201` a létrehozotthoz, `204` a tartalom nélkülihez, stb.

## Dinamikus állapotkódok és fejlécek a Response objektumon keresztül

```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
```

A `Response` paraméter injektálása lehetővé teszi az állapotkód és fejlécek **feltételesen** beállítását a futási időben.

## Hibák: HTTPException felvetése

```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
```

A hibaválaszokhoz a `raise HTTPException(...)` az idiomatikus módszer — beállítja az állapotot, a JSON `detail` üzenetet és az opcionális fejléceket.

## Egyéni Response közvetlen visszaadása

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

## Miért fontos ez

A helyes állapotkódok és fejlécek elengedhetetlenek az olyan helyes, jól működő REST API-k felépítéséhez, amelyekre az ügyfelek és az eszközök a szabványos HTTP-szemantikára támaszkodnak (201 a létrehozotthoz, 404 a nem találhatóhoz, 204 a tartalom nélkülihez stb.), ezért a helyes kód visszaadása a minőségi API-szerződés része.

A FastAPI tiszta vezérlést ad: az alapértelmezett `status_code` az útvonalon a szokásos esetre, az injektálható `Response` objektum a dinamikus kódok/fejlécekhez, és a `HTTPException` az idiomatikus módszer a hibák jelzésére megfelelő állapot- és JSON-részletekkel.

Ez a mechanizmusok megértése — és az `status` konstansok tisztázás céljából való felhasználása — mindennapi tudás az olyan API-k felépítéséhez, amelyek helyesen viselkednek és világosan kommunikálnak fogyasztóikkal.