Response Status Code

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

from fastapi import FastAPI

app = FastAPI()


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

status_codeパラメータは、HTTPステータスコードを含む数値を受け取ります。
status_code は代わりに、Python の http.HTTPStatus のような IntEnum を受け取ることもできます
レスポンスでそのステータスコードが返却され、OpenAPI スキーマ（およびユーザーインターフェース）にドキュメント化される。 HTTPでは、レスポンスの一部として3桁の数字のステータスコードを送信します。
これらのステータスコードは、それらを認識するために関連付けられた名前を持っていますが、重要な部分は数字です。簡単に言うと
- 100以上は「情報」のためのものです。直接使用することはほとんどありません。これらのステータスコードを持つレスポンスは本文を持つことができません。
- 200以上は「成功」の回答です。これらは最もよく使用するものです。
  - 200 はデフォルトのステータスコードで、すべてが「OK」であったことを意味します。
  - 他の例としては、201、"Created "があります。これは、データベースに新しいレコードを作成した後によく使用されます。
  - 特殊なケースとしては、204, "No Content "があります。このレスポンスは、クライアントに返すコンテンツがない場合に使用されます。
- 300以上は「リダイレクト」です。これらのステータスコードを持つレスポンスにはボディがあってもなくてもかまいませんが、304「Not Modified」を除き、ボディを持つ必要はありません。
- 400 以上は「クライアントエラー」応答です。これらは、おそらく最もよく使用される 2 番目のタイプです。例として、404は「見つかりませんでした」という応答です。クライアントからの一般的なエラーには、400を使用することができます。
- 500以上はサーバエラー用です。これらを直接使うことはほとんどありません。アプリケーションコードやサーバのどこかで何か問題が発生した場合、これらのステータスコードのいずれかが自動的に返されます。

Shortcut to remember the names

201は'created'を表す
しかし、これらのコードのそれぞれの意味を暗記する必要はありません。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}

Form Data

JSONの代わりにフォームフィールドを受け取る必要がある場合は、Formを使用する
フォームを使うには、まず python-multipart をインストールします。

from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

Define Form parameters

ボディやクエリの場合と同じ方法でフォームパラメータを作成します。
例えば、OAuth2仕様が使用できる方法の一つ(「パスワードフロー」と呼ばれる)では、ユーザ名とパスワードをフォームフィールドとして送信することが要求されています。
この仕様では、フィールドは正確に username と password と名付けられ、JSON ではなくフォームフィールドとして送信されることが要求されています。
Form を使えば、Body (および Query, Path, Cookie) と同じメタデータとバリデーションを宣言することができます。
FormはBodyを直接継承したクラスです。
フォームのボディを宣言するには、明示的に Form を使う必要があります。 ## About "Form Fields"
HTMLフォーム()がサーバーにデータを送信する方法は、通常そのデータのために「特別な」エンコーディングを使用しますが、JSONとは異なります。
FastAPIは、JSONの代わりに正しい場所からそのデータを読み取るようにします。
フォームからのデータは通常、"media type" application/x-www-form-urlencoded を使ってエンコードされます。
しかし、フォームがファイルを含む場合、それはmultipart/form-dataとしてエンコードされます。ファイルの扱いについては次の章で説明します。
パス操作で複数のFormパラメータを宣言することができますが、リクエストがapplication/jsonではなくapplication/x-www-form-urlencodedを使用してエンコードされたボディを持つことになるので、JSONとして受け取ることを期待しているBodyフィールドも宣言することはできません。これはFastAPIの制限ではなく、HTTPプロトコルの一部です。 ## まとめフォームデータの入力パラメータを宣言するには Form を使用します。

Request Files

クライアントがアップロードするファイルは、Fileを使ってデータ管理します。
FileはFormを直接継承するクラスです。しかし、Fastapi から Query, Path, File などをインポートするとき、これらは実際には特別なクラスを返す関数であることを覚えておいてください。
Fileのボディを宣言するには、Fileを使用する必要があります。そうしないと、パラメータがクエリパラメータやボディ(JSON)パラメータとして解釈されてしまうからです。
ファイルは「form data」としてアップロードされます。
パス操作関数のパラメータの型をByteと宣言すると、FastAPIがファイルを読み込んで、内容をByteで受け取ることになります。
これは、コンテンツ全体がメモリに保存されることを意味することを覚えておいてください。これは小さなファイルには有効です。
UploadFile を使用することで恩恵を受けることができるケースがいくつかあります。 ## File parameters with UploadFile
File パラメータを UploadFile 型で定義します。
UploadFileを使用すると、Byteよりもいくつかの利点があります。
それは、"スプール(処理対象を一時的に置いておく)された "ファイルを使用しています。最大サイズの制限までメモリに保存されたファイルで、この制限を通過した後、それはディスクに格納されます。これは、画像、ビデオ、大きなバイナリなどの大きなファイルでもメモリを消費せずにうまく動作することを意味します。
アップロードしたファイルからメタデータを取得できます。ファイルライクな非同期インターフェースを持っています。
これは実際の Python SpooledTemporaryFile オブジェクトを公開しており、ファイルライクなオブジェクトを期待する他のライブラリに直接渡すことができます。 ### UploadFile UploadFileには以下の属性があります。
filename
- アップロードされた元のファイル名 (例: myimage.jpg) を持つ文字列。
content_type。
- コンテンツタイプ (MIME タイプ / メディアタイプ) (例: image/jpeg) の str。
file:
- SpooledTemporaryFile（ファイルのようなオブジェクト）。これは実際のPythonファイルで、"file-like "オブジェクトを期待する他の関数やライブラリに直接渡すことができます。

UploadFile には以下の非同期メソッドがあります。これらはすべて、（内部の SpooledTemporaryFile を使用して）その下にある対応するファイルメソッドを呼び出します。
- write(data)。データ(strまたはバイト)をファイルに書き込みます。
- read(size): ファイルのサイズ(int)バイト/文字を読み込みます。ファイルのサイズ(int)バイト/文字を読み込みます。
- seek(offset): ファイルのバイト位置のオフセットを求めます。ファイルのバイト位置のオフセット(int)に移動します。
- 例えば、 await myfile.seek(0) はファイルの先頭に行きます。これは、一度だけ await myfile.read() を実行した後、再度内容を読み込む必要がある場合に特に便利です。
- close() :ファイルを閉じます。
- これらのメソッドはすべて非同期メソッドなので、asyncを使用する必要があります。

What is "Form Data"

HTMLフォーム()がサーバーにデータを送信する方法は、通常そのデータのために「特別な」エンコーディングを使用しますが、JSONとは異なります。
FastAPIは、JSONの代わりに正しい場所からそのデータを読み取るようにします。
フォームからのデータは通常、ファイルを含まない場合、application/x-www-form-urlencodedという "media type "を使ってエンコードされます。
しかし、フォームにファイルが含まれている場合、マルチパート/フォームデータとしてエンコードされます。Fileを使用する場合、FastAPIは正しい部分からファイルを取得しなければならないことを知っています。
これらのエンコーディングとフォームフィールドの詳細については、POST の MDN ウェブドキュメントを参照してください。
パス操作で複数のファイルとフォームパラメータを宣言することができますが、JSONとして受け取ることを期待しているボディフィールドも宣言することはできません。これはFastAPIの制限ではなく、HTTPプロトコルの一部です。

まとめ

入力パラメータとして（フォームデータとして）アップロードするファイルを宣言するにはFileを使用します。

Request Forms and Files

ファイルとフォームは同時に定義することができます。
ファイルやフォームのパラメータは、ボディやクエリの場合と同じように作成します。
ファイルやフォームフィールドがフォームデータとしてアップロードされ、ファイルやフォームフィールドを受け取ることになります。
そして、一部のファイルをバイトで、一部のファイルをUploadFileとして宣言することができます。

まとめ

同じリクエストでデータやファイルを受信する必要がある場合は、ファイルとフォームを一緒に使用します。

Handling Errors

APIを使用しているクライアントになんのエラーが起きているかを返す必要がある
例
- その操作のための権限がありません。
- リソースにアクセスできません。
- アクセスしようとしていたアイテムは存在しません。

これらの場合、通常は 400 の範囲 (400 から 499) の HTTP ステータスコードを返します。
- これは、200 の HTTP ステータスコード (200 から 299) に似ています。これらの "200" ステータスコードは、何らかの形でリクエストに "成功" したことを意味します。400の範囲のステータスコードは、クライアントからのエラーがあったことを意味します。

Use HTTPException

HTTP レスポンスをクライアントにエラーで返すには、HTTPException を使用します。

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

Raise an HTTPException in your code

HTTPExceptionは通常のPythonの例外にAPIに関連するデータを追加したものです。Pythonの例外なので、返却するのではなく、発生させるのです。
これはまた、パス操作関数の内部で呼び出しているユーティリティ関数の内部からHTTPExceptionを発生させた場合、パス操作関数の残りのコードを実行するのではなく、そのリクエストをすぐに終了させ、HTTPExceptionからのHTTPエラーをクライアントに送信することを意味しています。値を返すよりも例外を発生させることの利点については、依存関係とセキュリティの項で詳しく説明します。
この例では、クライアントが存在しない ID でアイテムをリクエストした場合、ステータスコード 404 で例外を発生させます。 ### The resulting response
クライアントが http://example.com/items/foo (item_id "foo") をリクエストした場合、そのクライアントは HTTP ステータスコード 200 と JSON レスポンスを受け取ります。
しかし、クライアントが http://example.com/items/bar (存在しない item_id "bar") をリクエストした場合、そのクライアントは HTTP ステータスコード 404 (「見つかりませんでした」エラー) と JSON レスポンスを受け取ります。
HTTPException を発生させる際には、str に限らず JSON に変換できる値をパラメータの詳細として渡すことができ、dictやリストなどを渡すことができます。
これらはFastAPIによって自動的に処理され、JSONに変換されます。 ## Add custom headers
HTTP エラーにカスタムヘッダを追加できると便利な状況がいくつかあります。おそらくコードの中で直接使用する必要はないでしょうが、複雑なAPIを開発したい時にはカスタムヘッダを追加することができます。

@app.get("/items-header/{item_id}")
async def read_item_header(item_id: str):
    if item_id not in items:
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "There goes my error"},
        )
    return {"item": items[item_id]}

# response
## response body
{
  "detail": "Item not Found"
}
## response headers
content-length: 27 
content-type: application/json 
date: Sat,13 Feb 2021 04:41:15 GMT 
server: uvicorn 
x-error: There goes my error

Install custom exception handlers

FastAPIではStarlette と同様、例外ユーティリティを使って、カスタム例外ハンドラを追加することができます。

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse


class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
    )


@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"unicorn_name": name}

例えば、自分(または使用するライブラリ)が発生させる可能性のあるカスタム例外UnicornExceptionがあるとします。そして、この例外を FastAPI でグローバルに処理したいとします。
その時はカスタム例外ハンドラを @app.exception_handler() で追加することができます。
ここで、/unicorns/yoloをリクエストすると、パス操作でUnicornExceptionが発生し、unicorn_exception_handler によって処理されます。そのため、HTTPステータスコードが418、JSONが返却されます
starlette.requestからRequestをインポートし、starlette.responsからJSONResponseをインポートするという方法もあります。
FastAPIは開発者であるあなたの利便性のためだけに、同じstarlette.responsをfastapi.responsと同じように提供しています。しかし、利用可能なレスポンスのほとんどはStarletteから直接取得できます。Requestも同じです。 ## Override the default exception handlers
FastAPI にはいくつかのデフォルト例外ハンドラがあります。これらのハンドラは、HTTPException を発生させた場合や、リクエストに無効なデータがある場合に、デフォルトの JSON レスポンスを返す役割を担っています。これらの例外ハンドラを独自にオーバーライドすることができます。
リクエストに無効なデータが含まれている場合、FastAPIは内部的にRequestValidationErrorを発生させます。また、そのためのデフォルトの例外ハンドラも含まれています。
これをオーバーライドするには、RequestValidationErrorをインポートし、@app.exception_handler(RequestValidationError)で使用して例外ハンドラを装飾します。例外ハンドラはRequestと例外を受け取ります。 ## Use the RequestValidationError body
RequestValidationErrorには、無効なデータで受信したボディが含まれています。
アプリの開発中に、ボディをログに記録してデバッグしたり、ユーザーに返したりするために使用できます。

from fastapi import FastAPI, Request, status
from fastapi.encoders import jsonable_encoder
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel

app = FastAPI()


@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content=jsonable_encoder({"detail": exc.errors(), "body": exc.body}),
    )


class Item(BaseModel):
    title: str
    size: int


@app.post("/items/")
async def create_item(item: Item):
    return item

下記のような不正なリクエストを送った場合

{
  "title": "towel",
  "size": "XL"
}

受信したボディを含むデータが無効であることを示すレスポンスを受信します。

{
  "detail": [
    {
      "loc": [
        "body",
        "size"
      ],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ],
  "body": {
    "title": "towel",
    "size": "XL"
  }
}

FastAPI's HTTPException vs Starlette's HTTPException

FastAPIには独自のHTTPExceptionがあります。そして、FastAPIのHTTPExceptionエラークラスはStarletteのHTTPExceptionエラークラスを継承しています。唯一の違いは、FastAPI の HTTPException ではレスポンスにヘッダを追加することができる点です。これは OAuth 2.0 やいくつかのセキュリティユーティリティで内部的に必要/使用されています。そのため、コード内では通常通り FastAPI の HTTPException を発生させ続けることができます。
しかし、例外ハンドラを登録する際には、Starlette の HTTPException 用に登録する必要があります。そうすれば、Starlette の内部コードや Starlette の拡張機能やプラグインのいずれかの部分が Starlette HTTPException を発生させた場合でも、ハンドラがそれをキャッチして処理できるようになります。
この例では、同じコード内で両方の HTTPException を発生させられるようにするために、Starlette の例外の名前を StarletteHTTPException に変更しています。

Re-use FastAPI's exception handlers

また、何らかの方法で例外を使用したい場合は、FastAPIから同じデフォルトの例外ハンドラを使用することもできます。
fastapi.exception_handlersからデフォルトの例外ハンドラをインポートして再利用することができます。

Path Operation Configuration

パス操作デコレータを設定するためにパス操作デコレータに渡すことができるパラメータがいくつかあります。