Kako postavljate kodove statusa i zaglavlja?

Question

Accepted Answer

FastAPI prema zadanoj postavci vraća `200 OK`, ali vi kontrolirate **kod statusa** (putem dekoratora ili objekta odgovora) i **zaglavlja** kada trebate drugačije ponašanje — važno je za odgovarajuću REST semantiku.

## Postavljanje zadane šifre statusa na ruti

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

Parametar `status_code` dekoratora postavlja zadanu šifru statusa uspjeha. Korištenje konstanti `status` (npr. `status.HTTP_201_CREATED`) je jasnija od magičnih brojeva. Točni kodovi su važni: `201` za kreirano, `204` za bez sadržaja, itd.

## Dinamički kodovi statusa i zaglavlja putem objekta 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
```

Injekcija parametra `Response` omogućuje vam da postavite kod statusa i zaglavlja **uvjetno** tijekom izvođenja.

## Greške: bacite 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
```

Za odgovore s greškama, `raise HTTPException(...)` je idiomatski način — postavlja status, JSON poruku `detail` i opcionalna zaglavlja.

## Vraćanje prilagođenog odgovora izravno

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

## Zašto je to važno

Ispravni kodovi statusa i zaglavlja neophodni su za izgradnju ispravnih, dobro ponašanih REST API-ja — klijenti i alati oslanjaju se na standardnu HTTP semantiku (201 za kreirano, 404 za nije pronađeno, 204 za bez sadržaja, itd.), tako da vraćanje ispravnog koda dio je kvalitetnog API ugovora.

FastAPI vam daje jasnu kontrolu: zadanu `status_code` na ruti za čest slučaj, injectables `Response` objekt za dinamičke kodove/zaglavlja, i `HTTPException` kao idiomatski način za signaliziranje grešaka s odgovarajućim statusom i JSON detaljima.

Razumijevanje ovih mehanizama — i korištenje konstanti `status` za jasnoću — svakodnevno je znanje za izgradnju API-ja koji se ponašaju ispravno i jasno komuniciraju sa svojima potrošačima.