როგორ დააყენებთ სტატუს კოდებს და Headers-ს?

Question

Accepted Answer

FastAPI სტანდარტულად აბრუნებს `200 OK`-ს, მაგრამ თქვენ შეგიძლიათ აკონტროლოთ **სტატუს კოდი** (დეკორატორის ან პასუხის ობიექტის მეშვეობით) და **headers** როდესაც გჭირდებათ განსხვავებული ქცევა — მნიშვნელოვანია სწორი 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` პასუხი არა აქვს, და ა.შ.

## დინამიური სტატუს კოდები და headers 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` პარამეტრის ინჯექცია საშუალებას გაძლევთ დააყენოთ სტატუს კოდი და headers **პირობითად** runtime-ზე.

## ошибки: raise 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` მესიჯს და ოპციონალურ headers-ს.

## მომხმარებლის სპეციფიკური Response-ის უშუალო დაბრუნება

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

## რატომ არის მნიშვნელოვანი

სწორი სტატუს კოდები და headers არის აუცილებელი სწორი, კარგად მოქმედი REST API-ების შესაქმნელად — კლიენტები და ინსტრუმენტები ეყრდნობიან სტანდარტულ HTTP სემანტიკას (201 შეიქმნა, 404 ვერ მოიძებნა, 204 პასუხი არა აქვს, და ა.შ.), ამიტომ სწორი კოდის დაბრუნება API ხარისხის ხელშეკრულების ნაწილია.

FastAPI იძლევა სუფთა კონტროლს: დეფოლტი `status_code` მარშრუტზე ჩვეულებრივი შემთხვევისთვის, ინჯექციის შესაძლო `Response` ობიექტი დინამიური კოდებისა და headers-ისთვის, და `HTTPException` როგორც იდიომატური გზა ნაკლებობის სიგნალის გამოსახატავად შესაბამისი სტატუსით და JSON detail-ით.

ეს მექანიზმების გაგება — და `status` კონსტანტების გამოყენება სიცხადისთვის — წაბლის ცოდნაა სწორი ქცევის API-ების აგებისა და მათი მომხმარებელთან გასაგებით კომუნიკაციისთვის.