Durum kodlarını ve başlıkları nasıl ayarlarsınız?

Question

Accepted Answer

FastAPI varsayılan olarak `200 OK` döndürür, ancak farklı bir davranışa ihtiyaç duyduğunuzda **durum kodunu** (dekoratör veya response nesnesi aracılığıyla) ve **başlıkları** kontrol edersiniz — bu doğru REST semantiği için önemlidir.

## Rotada varsayılan durum kodunu ayarlama

```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` dekoratör parametresi varsayılan başarı durumunu ayarlar. `status` sabitlerini kullanmak (ör. `status.HTTP_201_CREATED`) sihirli sayılardan daha açıktır. Doğru kodlar önemlidir: oluşturulan için `201`, içerik yok için `204`, vb.

## Response nesnesi aracılığıyla dinamik durum kodları ve başlıkları

```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` parametresini enjekte etmek, çalışma zamanında **koşullu** olarak durum kodunu ve başlıkları ayarlamanıza izin verir.

## Hatalar: HTTPException yükseltin

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

Hata yanıtları için `raise HTTPException(...)` idiyomatik yoldur — durumu, bir JSON `detail` mesajını ve isteğe bağlı başlıkları ayarlar.

## Özel bir Response'u doğrudan döndürme

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

## Neden önemli

Doğru durum kodları ve başlıklar, doğru ve iyi davranış gösteren REST API'ları oluşturmak için gereklidir — istemciler ve araçlar standart HTTP semantiğine (oluşturulan için 201, bulunamayan için 404, içerik yok için 204, vb.) güvenirler, bu nedenle doğru kodu döndürmek kaliteli bir API sözleşmesinin parçasıdır.

FastAPI size net kontrol sağlar: genel durum için rota üzerinde varsayılan `status_code`, dinamik kodlar/başlıklar için enjekte edilebilir `Response` nesnesi ve uygun durum ve JSON ayrıntılarıyla hataları sinyal vermek için idiyomatik yol olarak `HTTPException`.

Bu mekanizmaları anlamak — ve açıklık için `status` sabitlerini kullanmak — doğru şekilde davranış gösteren ve tüketicileriyle açık bir şekilde iletişim kuran API'lar oluşturmak için günlük bilgidir.