ステータスコードとヘッダーはどのように設定しますか？

Question

Accepted Answer

FastAPIはデフォルトで `200 OK` を返しますが、**ステータスコード**（デコレータまたはレスポンスオブジェクト経由）と**ヘッダー**は、異なる動作が必要な場合に制御できます — 適切なREST意味論のために重要です。

## なぜ重要なのか

適切なステータスコードとヘッダーは、正しくて良く動作するREST APIを構築するために不可欠です — クライアントとツールは標準的なHTTP意味論（作成は201、見つからないは404、コンテンツなしは204など）に依存しているため、正しいコードを返すことはAPI品質契約の一部です。

```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` はコンテンツなし、など。

```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` パラメータを注入すると、実行時に**条件付きで**ステータスコードとヘッダーを設定できます。

```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` メッセージ、およびオプションのヘッダーを設定します。

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

FastAPIはクリーンな制御を提供します：一般的なケースのためのルート上のデフォルト `status_code`、動的コード/ヘッダーのための注入可能な `Response` オブジェクト、および適切なステータスとJSON detailを含むエラーを通知するイディオマティックな方法として `HTTPException`。

これらのメカニズムを理解すること — と明確性のために `status` 定数を使うこと — は、正しく動作し、消費者と明確に通信するAPIを構築するための日常知識です。