Pfad-Parameter¶

Sie können Pfad-„Parameter“ oder -„Variablen“ mit der gleichen Syntax deklarieren, welche in Python-Formatstrings verwendet wird:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id):
    return {"item_id": item_id}

Der Wert des Pfad-Parameters item_id wird Ihrer Funktion als das Argument item_id übergeben.

Wenn Sie also dieses Beispiel ausführen und auf http://127.0.0.1:8000/items/foo gehen, sehen Sie als Response:

{"item_id":"foo"}

Pfad-Parameter mit Typen¶

Sie können den Typ eines Pfad-Parameters in der Funktion deklarieren, mit Standard-Python-Typannotationen:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

In diesem Fall wird item_id als int deklariert.

Daten-Konversion¶

Wenn Sie dieses Beispiel ausführen und Ihren Browser unter http://127.0.0.1:8000/items/3 öffnen, sehen Sie als Response:

{"item_id":3}

Datenvalidierung¶

Wenn Sie aber im Browser http://127.0.0.1:8000/items/foo besuchen, erhalten Sie eine hübsche HTTP-Fehlermeldung:

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": [
        "path",
        "item_id"
      ],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

denn der Pfad-Parameter item_id hatte den Wert "foo", was kein int ist.

Die gleiche Fehlermeldung würde angezeigt werden, wenn Sie ein float statt eines ints übergeben würden, wie etwa in: http://127.0.0.1:8000/items/4.2

Dokumentation¶

Und wenn Sie die Seite http://127.0.0.1:8000/docs in Ihrem Browser öffnen, sehen Sie eine automatische, interaktive API-Dokumentation wie:

Standardbasierte Vorteile, alternative Dokumentation¶

Und weil das generierte Schema vom OpenAPI-Standard kommt, gibt es viele kompatible Tools.

Aus diesem Grund bietet FastAPI selbst eine alternative API-Dokumentation (verwendet ReDoc), welche Sie unter http://127.0.0.1:8000/redoc einsehen können:

Auf die gleiche Weise gibt es viele kompatible Tools. Inklusive Codegenerierungstools für viele Sprachen.

Pydantic¶

Die ganze Datenvalidierung wird hinter den Kulissen von Pydantic durchgeführt, Sie profitieren also von dessen Vorteilen. Und Sie wissen, dass Sie in guten Händen sind.

Sie können die gleichen Typdeklarationen auch mit str, float, bool und vielen anderen komplexen Datentypen verwenden.

Mehrere davon werden in den nächsten Kapiteln des Tutorials erkundet.

Die Reihenfolge ist wichtig¶

Wenn Sie Pfadoperationen erstellen, haben Sie manchmal Situationen, in denen Sie einen fixen Pfad haben.

Etwa /users/me, sagen wir, um Daten über den aktuellen Benutzer zu erhalten.

Und Sie können auch einen Pfad /users/{user_id} haben, um Daten über einen spezifischen Benutzer mittels irgendeiner Benutzer-ID zu erhalten.

Weil Pfadoperationen in ihrer Reihenfolge ausgewertet werden, müssen Sie sicherstellen, dass der Pfad für /users/me vor dem für /users/{user_id} deklariert wurde:

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

Ansonsten würde der Pfad für /users/{user_id} auch auf /users/me passen und „denken“, dass er einen Parameter user_id mit dem Wert "me" erhält.

Ebenso können Sie eine Pfadoperation nicht erneut definieren:

from fastapi import FastAPI

app = FastAPI()


@app.get("/users")
async def read_users():
    return ["Rick", "Morty"]


@app.get("/users")
async def read_users2():
    return ["Bean", "Elfo"]

Die erste Definition wird immer verwendet werden, da ihr Pfad zuerst übereinstimmt.

Vordefinierte Werte¶

Wenn Sie eine Pfadoperation haben, welche einen Pfad-Parameter erhält, aber Sie wollen, dass die möglichen gültigen Pfad-Parameter-Werte vordefiniert sind, können Sie ein Standard-Python-Enum verwenden.

Eine Enum-Klasse erstellen¶

Importieren Sie Enum und erstellen Sie eine Unterklasse, die von str und Enum erbt.

Indem Sie von str erben, weiß die API-Dokumentation, dass die Werte vom Typ string sein müssen, und wird in der Lage sein, korrekt zu rendern.

Erstellen Sie dann Klassen-Attribute mit festgelegten Werten, welche die verfügbaren gültigen Werte sein werden:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Einen Pfad-Parameter deklarieren¶

Dann erstellen Sie einen Pfad-Parameter mit einer Typannotation, welche die von Ihnen erstellte Enum-Klasse (ModelName) verwendet:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Die Dokumentation testen¶

Weil die verfügbaren Werte für den Pfad-Parameter nun vordefiniert sind, kann die interaktive Dokumentation diese hübsch anzeigen:

Mit Python-Enumerationen arbeiten¶

Der Wert des Pfad-Parameters wird ein Member einer Enumeration sein.

Enumeration-Member vergleichen¶

Sie können ihn mit dem Enumeration-Member in Ihrem erstellten Enum ModelName vergleichen:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Enumerations-Wert erhalten¶

Den tatsächlichen Wert (in diesem Fall ein str) erhalten Sie mittels model_name.value, oder generell, your_enum_member.value:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Enumeration-Member zurückgeben¶

Sie können Enum-Member von Ihrer Pfadoperation zurückgeben, sogar verschachtelt in einem JSON-Body (z. B. als dict).

Diese werden zu ihren entsprechenden Werten konvertiert (in diesem Fall Strings), bevor sie an den Client zurückgegeben werden:

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

In Ihrem Client erhalten Sie eine JSON-Response wie:

{
  "model_name": "alexnet",
  "message": "Deep Learning FTW!"
}

Pfad-Parameter, die Pfade enthalten¶

Angenommen, Sie haben eine Pfadoperation mit einem Pfad /files/{file_path}.

Aber file_path soll selbst einen Pfad enthalten, etwa home/johndoe/myfile.txt.

Sprich, die URL für diese Datei wäre etwas wie: /files/home/johndoe/myfile.txt.

OpenAPI-Unterstützung¶

OpenAPI bietet nicht die Möglichkeit, zu deklarieren, dass ein Pfad-Parameter in sich einen Pfad enthalten kann, da das zu Szenarios führen könnte, die schwierig zu testen und zu definieren sind.

Trotzdem können Sie das in FastAPI tun, indem Sie eines der internen Tools von Starlette verwenden.

Die Dokumentation würde weiterhin funktionieren, allerdings ohne irgendeine Dokumentation hinzuzufügen, die besagt, dass der Parameter einen Pfad enthalten sollte.

Pfad-Konverter¶

Mittels einer Option direkt von Starlette können Sie einen Pfad-Parameter deklarieren, der einen Pfad enthält, indem Sie eine URL wie folgt definieren:

/files/{file_path:path}

In diesem Fall ist der Name des Parameters file_path, und der letzte Teil, :path, sagt ihm, dass der Parameter mit jedem Pfad übereinstimmen sollte.

Sie verwenden das also wie folgt:

from fastapi import FastAPI

app = FastAPI()


@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

Zusammenfassung¶

Mit FastAPI erhalten Sie mittels kurzer, intuitiver und Standard-Python-Typdeklarationen:

• Editor-Unterstützung: Fehlerprüfungen, Codevervollständigung, usw.
• Daten „parsen“
• Datenvalidierung
• API-Annotation und automatische Dokumentation

Und Sie müssen sie nur einmal deklarieren.

Das ist wahrscheinlich der wichtigste sichtbare Vorteil von FastAPI im Vergleich zu alternativen Frameworks (abgesehen von der rohen Performanz).