Jak ustawiać kody statusu i nagłówki?

Question

Accepted Answer

FastAPI domyślnie zwraca `200 OK`, ale kontrolujesz **kod statusu** (poprzez dekorator lub obiekt response) i **nagłówki** gdy potrzebujesz innego zachowania — jest to ważne dla prawidłowej semantyki REST.

## Ustawianie domyślnego kodu statusu na trasie

```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 dekoratora `status_code` ustawia domyślny status sukcesu. Używanie stałych `status` (np. `status.HTTP_201_CREATED`) jest jaśniejsze niż magiczne liczby. Prawidłowe kody są ważne: `201` dla utworzenia, `204` dla braku zawartości itp.

## Dynamiczne kody statusu i nagłówki poprzez obiekt 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
```

Injektowanie parametru `Response` pozwala ustawić kod statusu i nagłówki **warunkowo** w czasie wykonywania.

## Dlaczego to ważne

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

W przypadku odpowiedzi o błędach `raise HTTPException(...)` to idiomatyczny sposób — ustawia status, wiadomość JSON `detail` i opcjonalne nagłówki.

## Zwracanie niestandardowego Response bezpośrednio

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

Prawidłowe kody statusu i nagłówki są niezbędne do budowania poprawnych, dobrze zachowujących się REST API — klienci i narzędzia opierają się na standardowej semantyce HTTP (201 dla utworzenia, 404 dla nie znaleziono, 204 dla braku zawartości itp.), więc zwracanie prawidłowego kodu jest częścią umowy API o wysokiej jakości.

FastAPI daje ci czystą kontrolę: domyślny `status_code` na trasie dla standardowego przypadku, wstrzykiwalny obiekt `Response` dla dynamicznych kodów/nagłówków i `HTTPException` jako idiomatyczny sposób sygnalizowania błędów z odpowiednim statusem i JSON detail.

Zrozumienie tych mechanizmów — i użycie stałych `status` dla jasności — to wiedza codziennych wiadomości dla budowania API, które działają prawidłowo i komunikują się wyraźnie z ich konsumentami.