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

レスポンスモデルを指定するのと同じ方法で、レスポンスに使用されるHTTPステータスコードを以下のpath operationsのいずれかのstatus_codeパラメータで宣言することもできます。

@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など）のパラメータであることに注意してください。すべてのパラメータやボディのように、path operation関数のものではありません。

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

情報

status_codeは代わりに、Pythonのhttp.HTTPStatusのように、IntEnumを受け取ることもできます。

これは:

レスポンスでステータスコードを返します。
OpenAPIスキーマ（およびユーザーインターフェース）に以下のように文書化します:

備考

いくつかのレスポンスコード（次のセクションを参照）は、レスポンスにボディがないことを示しています。

FastAPIはこれを知っていて、レスポンスボディがないというOpenAPIドキュメントを生成します。

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

備考

すでにHTTPステータスコードが何であるかを知っている場合は、次のセクションにスキップしてください。

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

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

つまり:

100以上は「情報」のためのものです。。直接使うことはほとんどありません。これらのステータスコードを持つレスポンスはボディを持つことができません。
200 以上は「成功」のレスポンスのためのものです。これらは最も利用するであろうものです。
- 200はデフォルトのステータスコードで、すべてが「OK」であったことを意味します。
- 別の例としては、201（Created）があります。これはデータベースに新しいレコードを作成した後によく使用されます。
- 特殊なケースとして、204（No Content）があります。このレスポンスはクライアントに返すコンテンツがない場合に使用されます。そしてこのレスポンスはボディを持つことはできません。
300 以上は「リダイレクト」のためのものです。これらのステータスコードを持つレスポンスは304（Not Modified）を除き、ボディを持つことも持たないこともできます。
400 以上は「クライアントエラー」のレスポンスのためのものです。これらは、おそらく最も多用するであろう２番目のタイプです。
- 例えば、404は「Not Found」レスポンスです。
- クライアントからの一般的なエラーについては、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 は、開発者の利便性を考慮して、fastapi.statusと同じstarlette.statusを提供しています。しかし、これはStarletteから直接提供されています。

デフォルトの変更¶

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