Wie setzen Sie Statuscodes und Header?

Question

Accepted Answer

FastAPI gibt standardmäßig `200 OK` zurück, aber Sie steuern den **Statuscode** (über den Decorator oder das Response-Objekt) und **Header**, wenn Sie ein anderes Verhalten benötigen — wichtig für die richtige REST-Semantik.

## Festlegen eines Standard-Statuscodes auf der Route

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

Der Decorator-Parameter `status_code` legt den Standard-Erfolgsstatus fest. Die Verwendung von `status`-Konstanten (z. B. `status.HTTP_201_CREATED`) ist klarer als magische Zahlen. Richtige Codes sind wichtig: `201` für erstellt, `204` für kein Inhalt usw.

## Dynamische Statuscodes und Header über das Response-Objekt

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

Das Injizieren eines `Response`-Parameters ermöglicht es Ihnen, den Statuscode und die Header **zur Laufzeit bedingt** zu setzen.

## Fehler: HTTPException werfen

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

Für Fehlerantworten ist `raise HTTPException(...)` die idiomatische Methode — sie setzt den Status, eine JSON `detail`-Nachricht und optionale Header.

## Rückgabe eines benutzerdefinierten Response direkt

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

## Warum es wichtig ist

Korrekte Statuscodes und Header sind unverzichtbar für die Erstellung korrekter, gut funktionierender REST-APIs — Clients und Tools verlassen sich auf Standard-HTTP-Semantik (`201` für erstellt, `404` für nicht gefunden, `204` für kein Inhalt usw.), daher ist die Rückgabe des richtigen Codes Teil eines qualitativ hochwertigen API-Vertrags.

FastAPI gibt Ihnen saubere Kontrolle: einen Standard-`status_code` auf der Route für den allgemeinen Fall, das injizierbare `Response`-Objekt für dynamische Codes/Header und `HTTPException` als idiomatische Methode, um Fehler mit dem entsprechenden Status und einem JSON-Detail zu signalisieren.

Das Verständnis dieser Mechanismen — und die Verwendung von `status`-Konstanten zur Verdeutlichung — ist alltägliches Wissen für die Erstellung von APIs, die sich korrekt verhalten und klar mit ihren Nutzern kommunizieren.