Kako nastavite statusne kode in glave?

Question

Accepted Answer

FastAPI privzeto vrača `200 OK`, vendar nadzorujete **statusni kod** (prek okraška ali objekta response) in **glave**, kadar potrebujete drugačno vedenje — to je pomembno za pravilno REST semantiko.

## Nastavljanje privzetega statusnega koda na poti

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

Parameter okraška `status_code` nastavi privzeti status uspeha. Uporaba konstant `status` (npr. `status.HTTP_201_CREATED`) je jasnejša od magičnih številk. Pravilni kodeksi so pomembni: `201` za ustvarjeno, `204` za brez vsebine, itd.

## Dinamični statusni kodeksi in glave prek 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
```

Vnos parametra `Response` vam omogoča, da nastavite statusni kod in glave **pogojno** med izvajanjem.

## Napake: povišajte 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 odzive napak je `raise HTTPException(...)` idiomatičen način — nastavi status, JSON sporočilo `detail` in izbirne glave.

## Vrnitev prilagojenega Response neposredno

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

## Zakaj je to pomembno

Pravilni statusni kodeksi in glave so nujni za gradnjo pravilnih, dobro delujočih REST API-jev — odjemalci in orodja se zanašajo na standardno HTTP semantiko (201 za ustvarjeno, 404 za ne najdeno, 204 za brez vsebine, itd.), zato je vrnitev pravilnega koda del kakovostnega API pogodbe.

FastAPI vam daje čist nadzor: privzeti `status_code` na poti za pogost primer, vbrizgani objekt `Response` za dinamične kodekse/glave in `HTTPException` kot idiomatičen način za signalizacijo napak s primerno status kodo in JSON detajli.

Razumevanje teh mehanizmov — in uporaba konstant `status` za jasnost — je vsakodnevno znanje za gradnjo API-jev, ki se vedejo pravilno in jasno komunicirajo s svojimi potrošniki.