Kuinka asitat tilakoodit ja otsikot?

Question

Accepted Answer

FastAPI palauttaa `200 OK` oletuksena, mutta hallitset **tilakoodia** (dekoraattorin tai vastausobjektin kautta) ja **otsikoita**, kun tarvitset erilaista käyttäytymistä — tärkeää oikean REST-semantiikan kannalta.

## Oletustilakodin asittaminen reitille

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

`status_code`-dekoraattoriparametri asittaa oletusonnistumistilan. `status`-vakioiden käyttö (esim. `status.HTTP_201_CREATED`) on selkeämpää kuin taikkaluvut. Oikeat koodit ovat tärkeitä: `201` luodulle, `204` ei sisältöä jne.

## Dynaamiset tilakoodit ja otsikot Response-objektin kautta

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

`Response`-parametrin injektoiminen antaa sinulle mahdollisuuden asittaa tilakoodia ja otsikoita **ehdollisesti** ajon aikana.

## Virheet: Nosta 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
```

Virhevastauksille `raise HTTPException(...)` on idiomatinen tapa — se asittaa tilan, JSON `detail`-viestin ja valinnaiset otsikot.

## Mukautetun Response-objektin palauttaminen suoraan

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

## Miksi se on tärkeää

Oikeat tilakoodit ja otsikot ovat välttämättömiä oikeiden, hyvin käyttäytyvien REST-sovellusliittymien rakentamiselle — asiakkaat ja työkalut luottavat vakio HTTP-semantiikkaan (`201` luodulle, `404` ei löytynyt, `204` ei sisältöä jne.), joten oikean koodin palauttaminen on osa laadukkaan sovellusliittymän sopimusta.

FastAPI antaa sinulle puhtaan hallinnan: oletusarvoisen `status_code`-arvon reitille yleiselle tapaukselle, injektoitavan `Response`-objektin dynaamisille koodeille/otsikoille ja `HTTPException` idiomatisena tapana signaloida virheitä asianmukaisella tilalla ja JSON-yksityiskohdilla.

Näiden mekanismien ymmärtäminen — ja `status`-vakioiden käyttö selkeyden vuoksi — on jokapäiväistä tietoa sovellusliittymien rakentamiseen, jotka toimivat oikein ja kommunikoivat selvästi kuluttajiensa kanssa.