レスポンスステータスコード¶
レスポンスモデルを指定するのと同じ方法で、レスポンスに使用される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では、レスポンスの一部として3桁の数字のステータスコードを送信します。
これらのステータスコードは、それらを認識するために関連付けられた名前を持っていますが、重要な部分は番号です。
つまり:
100
以上は「情報」のためのものです。。直接使うことはほとんどありません。これらのステータスコードを持つレスポンスはボディを持つことができません。200
以上は「成功」のレスポンスのためのものです。これらは最も利用するであろうものです。200
はデフォルトのステータスコードで、すべてが「OK」であったことを意味します。- 別の例としては、
201
(Created)があります。これはデータベースに新しいレコードを作成した後によく使用されます。 - 特殊なケースとして、
204
(No Content)があります。このレスポンスはクライアントに返すコンテンツがない場合に使用されます。そしてこのレスポンスはボディを持つことはできません。
300
以上は「リダイレクト」のためのものです。これらのステータスコードを持つレスポンスは304
(Not Modified)を除き、ボディを持つことも持たないこともできます。400
以上は「クライアントエラー」のレスポンスのためのものです。これらは、おそらく最も多用するであろう2番目のタイプです。- 例えば、
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から直接提供されています。
デフォルトの変更¶
後に、高度なユーザーガイドで、ここで宣言しているデフォルトとは異なるステータスコードを返す方法を見ていきます。