Hoe stel je statuscodes en headers in?

Question

Accepted Answer

FastAPI retourneert standaard `200 OK`, maar je bepaalt de **statuscode** (via de decorator of het response-object) en **headers** wanneer je ander gedrag nodig hebt — belangrijk voor juiste REST-semantiek.

## Waarom het belangrijk is

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

De `status_code` decoratorparameter stelt de standaard successtatuscode in. Het gebruik van `status`-constanten (bijv. `status.HTTP_201_CREATED`) is duidelijker dan magische getallen. Juiste codes zijn belangrijk: `201` voor aangemaakt, `204` voor geen inhoud, enz.

## Dynamische statuscodes en headers via het Response-object

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

Een `Response`-parameter injecteren stelt je in staat de statuscode en headers **voorwaardelijk** tijdens runtime in te stellen.

## Fouten: HTTPException verhogen

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

Voor foutresponses is `raise HTTPException(...)` de idiomatische manier — het stelt de status, een JSON `detail`-bericht en optionele headers in.

## Een aangepaste Response rechtstreeks retourneren

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

Juiste statuscodes en headers zijn essentieel voor het bouwen van correcte, goed werkende REST API's — clients en tools vertrouwen op standaard HTTP-semantiek (201 voor aangemaakt, 404 voor niet gevonden, 204 voor geen inhoud, enz.), dus het retourneren van de juiste code maakt deel uit van een kwalitatief API-contract.

FastAPI geeft je schone controle: een standaard `status_code` op de route voor het normale geval, het injecteerbare `Response`-object voor dynamische codes/headers, en `HTTPException` als de idiomatische manier om fouten aan te geven met de juiste status en een JSON-detail.

Begrijpen van deze mechanismen — en het gebruik van `status`-constanten voor duidelijkheid — is dagelijkse kennis voor het bouwen van API's die correct werken en duidelijk communiceren met hun gebruikers.