レスポンスステータスコード¶

レスポンスモデルを指定できるのと同様に、任意の *パス操作* で `status_code` パラメータを使用して、レスポンスに使用される HTTP ステータスコードを宣言することもできます。

@app.get()
@app.post()
@app.put()
@app.delete()
など

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

注記

`status_code` は、「デコレータ」メソッド (`get`、`post` など) のパラメータであることに注意してください。すべてのパラメータやボディのように、*パス操作関数* のパラメータではありません。

`status_code` パラメータは、HTTP ステータスコードを表す数値を受け取ります。

情報

`status_code` は、Python の `http.HTTPStatus` などの `IntEnum` を受け取ることもできます。

これは以下のようになります。

レスポンスでそのステータスコードを返します。
OpenAPI スキーマ（したがって、ユーザーインターフェース）にそれをドキュメント化します。

注記

一部のレスポンスコード (次のセクションを参照) は、レスポンスにボディがないことを示しています。

FastAPI はこれを認識しており、レスポンスボディがないことを示す OpenAPI ドキュメントを作成します。

HTTPステータスコードについて¶

注記

HTTPステータスコードについてすでに知っている場合は、次のセクションに進んでください。

HTTP では、レスポンスの一部として 3 桁の数値ステータスコードを送信します。

これらのステータスコードには、認識するための名前が関連付けられていますが、重要な部分は数値です。

要するに

`100` 以上は「情報」用です。直接使用することはめったにありません。これらのステータスコードを持つレスポンスには、ボディを含めることができません。
**`200`** 以上は「成功」レスポンス用です。これらは最もよく使用するものです。
- `200` はデフォルトのステータスコードであり、すべてが「OK」だったことを意味します。
- 別の例として、`201`、「作成済み」があります。これは、データベースに新しいレコードを作成した後に一般的に使用されます。
- 特別なケースは `204`、「コンテンツなし」です。このレスポンスは、クライアントに返すコンテンツがない場合に使用されるため、レスポンスにボディを含めてはなりません。
**`300`** 以上は「リダイレクト」用です。これらのステータスコードを持つレスポンスには、ボディが含まれる場合と含まれない場合があります。ただし、`304`、「変更なし」はボディを含めてはなりません。
**`400`** 以上は「クライアントエラー」レスポンス用です。これらは、おそらく 2 番目に多く使用するタイプです。
- 例として、`404` は「見つかりません」レスポンス用です。
- クライアントからの一般的なエラーの場合は、`400` を使用できます。
`500` 以上はサーバーエラー用です。直接使用することはほとんどありません。アプリケーションコードまたはサーバーのどこかの部分で問題が発生した場合、これらのステータスコードのいずれかが自動的に返されます。

ヒント

各ステータスコードの詳細と、どのコードが何のためにあるかについては、MDN の HTTP ステータスコードに関するドキュメントを確認してください。

名前を覚えるためのショートカット¶

前の例をもう一度見てみましょう

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

`201` は「作成済み」のステータスコードです。

しかし、これらのコードの意味をそれぞれ覚える必要はありません。

`fastapi.status` の便利な変数を使用できます。

from fastapi import FastAPI, status

app = FastAPI()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

これらは単なる便宜上のものです。同じ数値を保持していますが、エディターのオートコンプリートを使用して見つけることができます。

技術詳細

from starlette import status を使用することもできます。

FastAPI は、開発者の便宜のために、starlette.status と同じものを fastapi.status として提供しています。しかし、これは Starlette から直接提供されています。

デフォルトの変更¶

後ほど、上級ユーザーガイドで、ここで宣言しているデフォルトとは異なるステータスコードを返す方法について説明します。