Jak nastavíte stavové kódy a záhlaví?

Question

Accepted Answer

FastAPI vrací `200 OK` ve výchozím nastavení, ale vy řídíte **stavový kód** (prostřednictvím dekorátoru nebo objektu response) a **záhlaví**, když potřebujete jiné chování — důležité pro správnou REST sémantiku.

## Nastavení výchozího stavového kódu na trase

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

Parametr dekorátoru `status_code` nastavuje výchozí stav úspěchu. Použití konstant `status` (např. `status.HTTP_201_CREATED`) je jasnější než magická čísla. Správné kódy jsou důležité: `201` pro vytvoření, `204` pro žádný obsah atd.

## Dynamické stavové kódy a záhlaví prostřednictvím objektu 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
```

Injektování parametru `Response` vám umožňuje nastavit stavový kód a záhlaví **podmínečně** za běhu.

## Chyby: vyvolat HTTPException

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

Pro chybové odpovědi je `raise HTTPException(...)` idiomatický způsob — nastavuje stav, zprávu JSON `detail` a volitelná záhlaví.

## Vrácení vlastního Response objektu přímo

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

## Proč na tom záleží

Správné stavové kódy a záhlaví jsou nezbytné pro vytváření správných a dobře se chování REST API — klienti a nástroje se spoléhají na standardní HTTP sémantiku (`201` pro vytvoření, `404` pro nenalezení, `204` pro žádný obsah atd.), takže vrácení správného kódu je součástí kvalitní API smlouvy.

FastAPI vám poskytuje čistou kontrolu: výchozí `status_code` na trase pro běžný případ, injektovatelný objekt `Response` pro dynamické kódy/záhlaví a `HTTPException` jako idiomatický způsob signalizace chyb s příslušným stavem a JSON detailem.

Pochopení těchto mechanismů — a použití konstant `status` pro jasnost — je každodenní znalostí pro vytváření API, které se chová správně a komunikuje jasně se svými spotřebiteli.