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

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

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

Python 3.8+

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 - 199 は「情報」用です。これらを直接使用することはめったにありません。これらのステータスコードを持つレスポンスにはボディを含めることはできません。
200 - 299 は「成功」レスポンス用です。これらは最もよく使用するものです。
- 200 はデフォルトのステータスコードで、すべてが「OK」だったことを意味します。
- 別の例は 201、「Created」です。これは通常、データベースに新しいレコードを作成した後に使用されます。
- 特別なケースは 204、「No Content」です。このレスポンスは、クライアントに返すコンテンツがない場合に使用され、そのためレスポンスにボディを含めるべきではありません。
300 - 399 は「リダイレクト」用です。これらのステータスコードを持つレスポンスにはボディが含まれる場合と含まれない場合がありますが、304、「Not Modified」の場合はボディを含めてはなりません。
400 - 499 は「クライアントエラー」レスポンス用です。これらはおそらく最もよく使用する2番目のタイプです。
- 例は 404 で、「Not Found」レスポンス用です。
- クライアントからの一般的なエラーには、400 を使用できます。
500 - 599 はサーバーエラー用です。これらを直接使用することはほとんどありません。アプリケーションコードまたはサーバーの一部で問題が発生すると、これらのステータスコードのいずれかが自動的に返されます。

ヒント

各ステータスコードとその用途について詳しく知るには、MDN の HTTP ステータスコードに関するドキュメントを確認してください。

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

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

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


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

201 は「Created」のステータスコードです。

しかし、これらのコードがそれぞれ何を意味するかを記憶する必要はありません。

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

Python 3.8+

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 から来ています。

デフォルトの変更¶

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