Unaweza kutenga kodha za hali na vichwa vipi?

Question

Accepted Answer

FastAPI hurejesha `200 OK` kwa chaguo-msingi, lakini unakontroleza **kodha ya hali** (kupitia mtambuzi au kitu cha jibu) na **vichwa** wakati unahitaji tabia tofauti — muhimu kwa semantiki sahihi ya REST.

## Tenga kodha ya hali ya chaguo-msingi kwenye njia

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

Parameter ya mtambuzi `status_code` inaweka hali ya mafanikio ya chaguo-msingi. Kutumia `status` constants (mfano `status.HTTP_201_CREATED`) ni wazi zaidi kuliko nambari za uchawi. Kodha sahihi ni muhimu: `201` kwa kuundwa, `204` kwa hakuna maudhui, n.k.

## Kodha za hali ya nguvu na vichwa kupitia kitu cha 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
```

Kuingiza parameter ya `Response` kukuruhusu weka kodha ya hali na vichwa **kulingana na sharti** wakati wa utekelezaji.

## Hitilafu: upalaze 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
```

Kwa majibu ya hitilafu, `raise HTTPException(...)` ni njia ya kawaida — inaweka hali, ujumbe wa JSON `detail`, na vichwa vya hiari.

## Rudisha Response iliyofanywa kwa binafsi moja kwa moja

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

## Kwa nini ni muhimu

Kodha sahihi za hali na vichwa ni muhimu kwa ujenzi wa REST API sahihi na zilizotendeka vizuri — wateja na zana hutegemea semantiki ya HTTP inayohusika (201 kwa kuundwa, 404 kwa haikupatikana, 204 kwa hakuna maudhui, n.k.), kwa hivyo kurudisha kodha sahihi ni sehemu ya mukataba wa API wa ubora.

FastAPI inakupa kontroli safi: `status_code` ya chaguo-msingi kwenye njia kwa kesi ya kawaida, kitu cha `Response` kinachoinzwa kwa kodha/vichwa vya nguvu, na `HTTPException` kama njia ya kawaida ya kusaini hitilafu na hali inayofaa na maelezo ya JSON.

Kuelewa utaratibu huu — na kutumia `status` constants kwa wazi — ni ujuzi wa kila siku kwa ujenzi wa API ambazo zinafanya vizuri na zikipumzika wazi na wanatumia zao.