Πώς ορίζετε κωδικούς κατάστασης και κεφαλίδες;

Question

Accepted Answer

Το FastAPI επιστρέφει `200 OK` εξ ορισμού, αλλά ελέγχετε τον **κωδικό κατάστασης** (μέσω του διακοσμητή ή του αντικειμένου response) και τις **κεφαλίδες** όταν χρειάζεστε διαφορετική συμπεριφορά — σημαντικό για τη σωστή σημασιολογία REST.

## Ορισμός προεπιλεγμένου κωδικού κατάστασης στη διαδρομή

```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` ορίζει την προεπιλεγμένη κατάσταση επιτυχίας. Η χρήση σταθερών `status` (π.χ. `status.HTTP_201_CREATED`) είναι σαφέστερη από τα μαγικά νούμερα. Οι σωστοί κωδικοί έχουν σημασία: `201` για δημιουργημένα, `204` για καμία περιεχόμενα κ.λπ.

## Δυναμικοί κωδικοί κατάστασης και κεφαλίδες μέσω του αντικειμένου 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
```

Η εισαγωγή ενός παραμέτρου `Response` σας επιτρέπει να ορίσετε τον κωδικό κατάστασης και τις κεφαλίδες **υπό όρους** κατά τη διάρκεια εκτέλεσης.

## Σφάλματα: Ύψωση 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
```

Για απαντήσεις σφάλματος, το `raise HTTPException(...)` είναι ο ιδιωματικός τρόπος — ορίζει την κατάσταση, ένα μήνυμα JSON `detail` και προαιρετικές κεφαλίδες.

## Επιστροφή ενός προσαρμοσμένου Response απευθείας

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

## Γιατί έχει σημασία

Οι σωστοί κωδικοί κατάστασης και οι κεφαλίδες είναι απαραίτητες για τη δημιουργία σωστών και καλά συμπεριφερόμενων REST API — οι πελάτες και τα εργαλεία βασίζονται στη σημασιολογία HTTP τυπική (`201` για δημιουργημένα, `404` για μη εύρεση, `204` για καμία περιεχόμενα κ.λπ.), επομένως η επιστροφή του σωστού κωδικού είναι μέρος ενός συμβολαίου API ποιότητας.

Το FastAPI σας δίνει καθαρό έλεγχο: έναν προεπιλεγμένο `status_code` στη διαδρομή για την κοινή περίπτωση, το έγχυτο αντικείμενο `Response` για δυναμικούς κωδικούς/κεφαλίδες, και `HTTPException` ως ιδιωματικός τρόπος σήμανσης σφαλμάτων με την κατάλληλη κατάσταση και λεπτομέρεια JSON.

Η κατανόηση αυτών των μηχανισμών — και η χρήση σταθερών `status` για σαφήνεια — είναι καθημερινή γνώση για τη δημιουργία API που συμπεριφέρονται σωστά και επικοινωνούν ξεκάθαρα με τους καταναλωτές τους.