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

レスポンスモデルを指定するのと同じように、任意の パスオペレーション で 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}

Note

status_code は、「デコレータ」メソッド（get、postなど）のパラメータであることに注意してください。すべてのパラメータとボディのように、パスオペレーション関数 のパラメータではありません。

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

情報

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

それは

レスポンスでそのステータスコードを返します。
OpenAPIスキーマ（およびユーザーインターフェース）にそのように記述します。

Note

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

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

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

Note

HTTPステータスコードが何であるかをご存知の場合は、次のセクションに進んでください。

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

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

簡単に言うと

100 - 199 は「情報」用です。これらを直接使用することはめったにありません。これらのステータスコードを持つレスポンスはボディを持つことができません。
200 - 299 は「成功」レスポンス用です。これらは最もよく使うものです。
- 200 はデフォルトのステータスコードで、すべてが「OK」であることを意味します。
- もう1つの例は 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から来ています。

デフォルトの変更¶

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