Bagaimana Anda mengatur kode status dan header?

Question

Accepted Answer

FastAPI mengembalikan `200 OK` secara default, tetapi Anda mengontrol **kode status** (melalui dekorator atau objek respons) dan **header** ketika Anda membutuhkan perilaku berbeda — penting untuk semantik REST yang tepat.

## Mengatur kode status default pada rute

```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 `status_code` dekorator menetapkan status keberhasilan default. Menggunakan konstanta `status` (mis. `status.HTTP_201_CREATED`) lebih jelas daripada angka ajaib. Kode yang benar penting: `201` untuk dibuat, `204` untuk tidak ada konten, dll.

## Kode status dan header dinamis melalui objek 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
```

Menyuntikkan parameter `Response` memungkinkan Anda mengatur kode status dan header **secara kondisional** saat runtime.

## Kesalahan: naikkan 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
```

Untuk respons kesalahan, `raise HTTPException(...)` adalah cara idiomatis — menetapkan status, pesan JSON `detail`, dan header opsional.

## Mengembalikan Respons kustom secara langsung

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

## Mengapa ini penting

Kode status dan header yang tepat sangat penting untuk membangun REST API yang benar dan berperilaku baik — klien dan alat mengandalkan semantik HTTP standar (201 untuk dibuat, 404 untuk tidak ditemukan, 204 untuk tidak ada konten, dll.), jadi mengembalikan kode yang benar adalah bagian dari kontrak API berkualitas.

FastAPI memberi Anda kontrol yang bersih: `status_code` default pada rute untuk kasus umum, objek `Response` yang dapat disuntikkan untuk kode/header dinamis, dan `HTTPException` sebagai cara idiomatis untuk memberi sinyal kesalahan dengan status yang sesuai dan detail JSON.

Memahami mekanisme ini — dan menggunakan konstanta `status` untuk kejelasan — adalah pengetahuan sehari-hari untuk membangun API yang berperilaku dengan benar dan berkomunikasi dengan jelas dengan konsumen mereka.