Si e vendosni kodin e statusit dhe kokat?

Question

Accepted Answer

FastAPI kthen `200 OK` si parazgjedhje, por ju kontrolloni **kodin e statusit** (përmes dekoratorit ose objektit të përgjigjes) dhe **kokat** kur keni nevojë për sjellje të ndryshme — e rëndësishme për semantikën e duhur REST.

## Vendosja e kodit të parazgjedhur të statusit në rrugë

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

Parametri `status_code` i dekoratorit vendos statusin e suksesit të parazgjedhur. Përdorimi i konstantave `status` (p.sh. `status.HTTP_201_CREATED`) është më i qartë se numrat magjikë. Kodet e duhura kanë rëndësi: `201` për të krijuar, `204` për pa përmbajtje, etj.

## Kodet dinamikë të statusit dhe kokat përmes objektit 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
```

Zgjedhja e parametrit `Response` ju lejon të vendosni kodin e statusit dhe kokat **me kusht** në kohën e ekzekutimit.

## Gabimet: lëshoni 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
```

Për përgjigjet e gabimit, `raise HTTPException(...)` është mënyra idiomatike — vendos statusin, një mesazh JSON `detail` dhe koka opsionale.

## Kthim i përgjigjes së personalizuar direkt

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

## Pse është e rëndësishme

Kodet e duhur të statusit dhe kokat janë thelbësorë për ndërtimin e API-ve REST të saktë dhe mirë të sjellur — klientët dhe mjetet mbështeten në semantikën standarde HTTP (201 për të krijuar, 404 për nuk u gjet, 204 për pa përmbajtje, etj.), kështu që kthimi i kodit të duhur është pjesë e kontratës API me cilësi.

FastAPI ju jep kontroll të pastër: një `status_code` të parazgjedhur në rrugë për rastin e zakonshëm, objektin e zgjedhur `Response` për kodet/kokatdinarike, dhe `HTTPException` si mënyra idiomatike për sinjalizimin e gabimeve me statusin e duhur dhe detajet JSON.

Kuptimi i këtyre mekanizmave — dhe përdorimi i konstantave `status` për qartësi — është njohuri e përditshme për ndërtimin e API-ve që sillen siç duhet dhe komunikojnë qartë me konsumatorët e tyre.