Tout ce que vous devez savoir sur les paramètres de requête FastAPI (avec les meilleures pratiques)

FastAPI est un framework web moderne et performant pour la création d'API avec Python. L'une de ses fonctionnalités les plus remarquables est la gestion des paramètres de requête FastAPI, qui permet aux développeurs de créer des API flexibles et conviviales. Dans cet article, nous allons explorer les meilleures pratiques et techniques pour utiliser efficacement les paramètres de requête FastAPI en 2024.

Pourquoi utiliser les paramètres de requête FastAPI ?

Flexibilité : Les paramètres de requête FastAPI permettent aux clients de personnaliser les résultats de leurs requêtes. Par exemple, les utilisateurs peuvent filtrer les résultats de recherche en fonction de critères spécifiques tels que la catégorie, le prix ou la note.
Convivialité : Ils simplifient l'interaction entre les clients et l'API. Les clients peuvent facilement ajouter des paramètres de requête à l'URL, tandis que les développeurs peuvent rapidement valider et traiter ces paramètres dans leur code.
Performance : En utilisant les paramètres de requête FastAPI, vous pouvez réduire le nombre de points de terminaison requis pour une API. Au lieu de créer des points de terminaison distincts pour chaque option de filtrage, un seul point de terminaison peut gérer plusieurs paramètres de requête.

Comment utiliser les paramètres de requête FastAPI

Définition des paramètres de requête FastAPI

Pour définir des paramètres de requête dans FastAPI, il suffit de les inclure en tant que paramètres de fonction dans la définition de votre point de terminaison. Voici un exemple de base :

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, max_length=50),
    skip: int = Query(default=0, ge=0),
    limit: int = Query(default=10, le=100)
):
    return {"q": q, "skip": skip, "limit": limit}

Dans cet exemple :

q : Un paramètre de chaîne facultatif avec une longueur maximale de 50 caractères.
skip : Un paramètre entier qui spécifie le nombre d'éléments à ignorer, avec une valeur par défaut de 0 et une valeur minimale de 0.
limit : Un paramètre entier qui spécifie le nombre maximal d'éléments à renvoyer, avec une valeur par défaut de 10 et une valeur maximale de 100.

Accès aux paramètres de requête FastAPI

Lorsqu'un client effectue une requête vers le point de terminaison, FastAPI extrait automatiquement les paramètres de requête de l'URL et les transmet à la fonction. Par exemple, si une requête est effectuée vers /items/?q=foo&skip=10&limit=5, la fonction recevra :

q = "foo"
skip = 10
limit = 5

Cette extraction automatique facilite l'utilisation des paramètres de requête FastAPI sans logique d'analyse supplémentaire.

Paramètres de requête FastAPI facultatifs et obligatoires

Par défaut, les paramètres de requête FastAPI sont facultatifs. Si un paramètre n'est pas fourni dans la requête, FastAPI utilisera la valeur par défaut spécifiée. Pour rendre un paramètre de requête obligatoire, il suffit d'omettre la valeur par défaut :

@app.get("/items/")
async def read_items(required_param: str):
    return {"required_param": required_param}

Si le required_param n'est pas inclus dans la requête, FastAPI renverra une erreur 422 Unprocessable Entity, indiquant qu'un paramètre de requête obligatoire est manquant.

Gestion de plusieurs valeurs pour les paramètres de requête FastAPI

FastAPI vous permet de définir un paramètre de requête qui peut accepter plusieurs valeurs. Vous pouvez le faire en spécifiant le type de paramètre sous forme de liste :

from typing import List

@app.get("/items/")
async def read_items(q: List[str] = Query(default=[])):
    return {"q": q}

Dans ce cas, le client peut effectuer une requête comme /items/?q=foo&q=bar&q=baz, et FastAPI analysera les valeurs dans une liste. Cette fonctionnalité est particulièrement utile pour les scénarios où les utilisateurs souhaitent filtrer les résultats en fonction de plusieurs critères.

💡

Vous cherchez à améliorer le développement de votre API ? Essayez Apidog. Cet outil puissant est parfait pour améliorer vos projets FastAPI et bien plus encore. Essayez-le gratuitement et voyez comment il peut rationaliser votre flux de travail et améliorer l'efficacité

button

Validation des paramètres de requête FastAPI

FastAPI fournit une validation intégrée pour les paramètres de requête à l'aide de la fonction Query. Vous pouvez spécifier des contraintes telles que des valeurs minimales et maximales, des restrictions de longueur et des modèles regex. Voici un exemple :

@app.get("/items/")
async def read_items(
    q: str = Query(default=None, min_length=3, max_length=50),
    item_id: int = Query(ge=1, le=100)
):
    return {"q": q, "item_id": item_id}

Dans cet exemple, q doit être une chaîne d'une longueur minimale de 3 et d'une longueur maximale de 50. Le item_id doit être un entier compris entre 1 et 100. FastAPI validera automatiquement ces contraintes et renverra une erreur si l'entrée ne répond pas aux critères spécifiés.

Génération automatique de documentation avec FastAPI et OpenAPI

L'un des avantages exceptionnels de l'utilisation de FastAPI est son intégration transparente avec OpenAPI, qui permet la génération automatique d'une documentation d'API interactive. Cette fonctionnalité améliore la convivialité de votre API et offre une meilleure expérience aux développeurs qui consomment votre API. Voici un aperçu de la façon dont FastAPI y parvient et comment vous pouvez améliorer la documentation de vos paramètres de requête.

Qu'est-ce qu'OpenAPI ?

OpenAPI est une spécification pour la création d'API qui fournit un moyen standard de décrire les capacités de votre API. Il permet aux humains et aux machines de comprendre les capacités d'un service sans accéder à son code source ni consulter d'autres documents. FastAPI exploite cette spécification pour générer automatiquement une documentation interactive pour vos points de terminaison d'API.

Comment FastAPI génère la documentation

Lorsque vous définissez votre application FastAPI et ses points de terminaison, FastAPI crée automatiquement un schéma OpenAPI basé sur les signatures de fonction et les types des paramètres que vous définissez. Ce schéma comprend :

Chemins des points de terminaison : Les routes que vous définissez dans votre application.
Méthodes HTTP : Les méthodes (GET, POST, PUT, DELETE, etc.) associées à chaque point de terminaison.
Paramètres : Paramètres de chemin et de requête, y compris leurs types, valeurs par défaut et contraintes.
Modèles de réponse : Le format de réponse attendu pour chaque point de terminaison.

Comment la documentation interactive avec FastAPI

FastAPI fournit deux interfaces de documentation interactives prêtes à l'emploi :

Swagger UI : Accessible à l'adresse /docs, cette interface permet aux utilisateurs d'explorer les points de terminaison de votre API, d'afficher les formats de requête et de réponse, et même de tester les points de terminaison directement à partir du navigateur.
ReDoc : Disponible à l'adresse /redoc, cette interface fournit une vue plus détaillée et structurée de la documentation de votre API, ce qui facilite la navigation et la compréhension des différents points de terminaison et de leurs paramètres.

Les deux interfaces sont générées automatiquement en fonction du schéma OpenAPI créé par FastAPI, ce qui garantit que votre documentation est toujours à jour avec votre code.

Amélioration de la documentation pour les paramètres de requête

Bien que FastAPI génère une documentation de base pour vos paramètres de requête, vous pouvez l'améliorer davantage en fournissant des descriptions détaillées, des exemples et des métadonnées supplémentaires. Voici comment :

Texte descriptif : Utilisez le paramètre description dans la fonction Query pour fournir des explications claires de ce que fait chaque paramètre de requête. Ceci est particulièrement utile pour les utilisateurs qui ne connaissent pas votre API.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="Terme de recherche pour filtrer les éléments."),
    skip: int = Query(default=0, ge=0, description="Nombre d'éléments à ignorer."),
    limit: int = Query(default=10, le=100, description="Nombre maximal d'éléments à renvoyer.")
):
    return {"q": q, "skip": skip, "limit": limit}

2. Exemples : Fournissez des exemples pour vos paramètres de requête afin d'illustrer comment ils peuvent être utilisés. Ceci est particulièrement utile pour les paramètres complexes ou lorsqu'il existe des formats spécifiques à respecter.

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="Terme de recherche pour filtrer les éléments.", example="pomme"),
    skip: int = Query(default=0, ge=0, description="Nombre d'éléments à ignorer.", example=5),
    limit: int = Query(default=10, le=100, description="Nombre maximal d'éléments à renvoyer.", example=20)
):
    return {"q": q, "skip": skip, "limit": limit}

3. Contraintes de validation : Indiquez clairement les contraintes de validation de vos paramètres de requête. Cela inclut les valeurs minimales et maximales, les restrictions de longueur et tous les formats spécifiques. FastAPI gère ces validations automatiquement, mais les documenter aide les utilisateurs à comprendre les limites.

4. Annotations de type : Utilisez des annotations de type appropriées pour vos paramètres de requête. FastAPI utilise ces annotations pour générer automatiquement les types de données attendus dans la documentation, ce qui aide les utilisateurs à comprendre quel type de données ils doivent fournir.

5. Regroupement des paramètres associés : Si votre API comporte plusieurs paramètres de requête associés, envisagez de les regrouper logiquement. Cela peut aider les utilisateurs à comprendre comment les paramètres interagissent les uns avec les autres et quelles combinaisons sont valides.

Avantages d'une documentation améliorée

Amélioration de la convivialité : Des paramètres de requête bien documentés permettent aux développeurs de comprendre plus facilement comment interagir avec votre API. Cela réduit la courbe d'apprentissage et augmente l'adoption.
Réduction des demandes d'assistance : Une documentation claire peut aider à répondre aux questions courantes et à réduire le nombre de demandes d'assistance que vous recevez des utilisateurs qui essaient de comprendre comment utiliser votre API.
Développement plus rapide : Les développeurs peuvent rapidement consulter la documentation lors de la création d'applications, ce qui accélère les cycles d'intégration et de développement.
Adoption accrue de l'API : Une documentation complète et conviviale peut attirer davantage de développeurs à utiliser votre API, améliorant ainsi son succès et sa portée globaux.
Cohérence : La documentation automatique garantit que votre documentation d'API est cohérente avec l'implémentation réelle, réduisant ainsi les divergences qui peuvent entraîner une confusion.

Techniques avancées pour les paramètres de requête FastAPI

Utilisation des énumérations pour les paramètres de requête FastAPI

Vous pouvez restreindre les paramètres de requête FastAPI à un ensemble de valeurs prédéfini à l'aide des énumérations Python. Ceci est utile pour les paramètres qui ne doivent accepter que des options spécifiques :

from enum import Enum

class ItemType(str, Enum):
    fruit = "fruit"
    vegetable = "vegetable"
    dairy = "dairy"

@app.get("/items/")
async def read_items(item_type: ItemType):
    return {"item_type": item_type}

Dans cet exemple, le paramètre de requête item_type ne peut être que l'une des valeurs définies dans l'énumération ItemType. Si le client fournit une valeur non valide, FastAPI renverra une erreur 422.

Dépendances des paramètres de requête

FastAPI vous permet de créer des dépendances pour les paramètres de requête, ce qui peut vous aider à réutiliser la logique sur plusieurs points de terminaison. Vous pouvez définir une fonction de dépendance qui renvoie une valeur basée sur les paramètres de requête :

from fastapi import Depends

def query_param_dependency(q: str | None = None):
    return q if q else "default"

@app.get("/items/")
async def read_items(q: str = Depends(query_param_dependency)):
    return {"q": q}

Dans cet exemple, la fonction query_param_dependency vérifie si le paramètre de requête q est fourni. Sinon, il renvoie une valeur par défaut. Cette approche favorise la réutilisation du code et maintient la propreté de vos fonctions de point de terminaison.

Gestion des erreurs pour les paramètres de requête FastAPI

FastAPI gère automatiquement les erreurs liées aux paramètres de requête. Si un paramètre de requête obligatoire est manquant ou si un paramètre échoue à la validation, FastAPI renvoie une réponse 422 Unprocessable Entity avec un message d'erreur détaillé. Vous pouvez personnaliser la gestion des erreurs en utilisant des gestionnaires d'exceptions :

from fastapi import HTTPException

@app.get("/items/")
async def read_items(q: str | None = Query(default=None)):
    if q is None:
        raise HTTPException(status_code=400, detail="Le paramètre de requête 'q' est obligatoire.")
    return {"q": q}

Cet exemple montre comment lever une exception HTTP personnalisée lorsqu'un paramètre de requête obligatoire n'est pas fourni. Cette approche vous permet de fournir des messages d'erreur plus informatifs aux clients.

Test des paramètres de requête FastAPI

Tester votre application FastAPI est essentiel pour vous assurer que vos paramètres de requête fonctionnent comme prévu. Vous pouvez utiliser la bibliothèque httpx pour effectuer des tests sur vos points de terminaison FastAPI. Voici un exemple :

import httpx
import pytest

@pytest.mark.asyncio
async def test_read_items():
    async with httpx.AsyncClient() as client:
        response = await client.get("http://localhost:8000/items/?q=test&skip=0&limit=10")
        assert response.status_code == 200
        assert response.json() == {"q": "test", "skip": 0, "limit": 10}

Dans ce test, nous effectuons une requête GET vers le point de terminaison /items/ avec des paramètres de requête et affirmons que la réponse est celle attendue. Les tests font partie intégrante du processus de développement, garantissant que votre API se comporte correctement lors de la gestion des paramètres de requête FastAPI.

Conclusion

Les paramètres de requête FastAPI sont une fonctionnalité puissante qui vous permet de transmettre des données supplémentaires à vos points de terminaison d'API via l'URL. Ils offrent flexibilité, convivialité et avantages en termes de performances lors de la création d'API avec FastAPI. Dans ce guide, nous avons exploré comment définir, accéder, valider et documenter les paramètres de requête FastAPI à l'aide d'exemples détaillés. Nous avons abordé des sujets tels que les paramètres facultatifs et obligatoires, les valeurs multiples, les types complexes et la génération automatique de documentation. Nous avons également discuté des techniques avancées, de la gestion des erreurs, des tests et des pièges courants. En tirant parti des paramètres de requête FastAPI, vous pouvez créer des API plus flexibles et conviviales qui peuvent gérer diverses exigences de filtrage, de tri et de pagination sans avoir besoin de plusieurs points de terminaison dédiés. N'oubliez pas de choisir des types de paramètres, des validations et des descriptions appropriés pour vous assurer que votre API est facile à utiliser et bien documentée pour vos clients. Les puissantes capacités de paramètres de requête de FastAPI peuvent améliorer considérablement les fonctionnalités et la convivialité de votre API, ce qui en fait un excellent choix pour les applications Web modernes.

Ressources supplémentaires sur FastAPI

Pour améliorer davantage votre compréhension des paramètres de requête FastAPI, pensez à explorer les ressources suivantes :

Documentation FastAPI : La documentation officielle de FastAPI fournit des informations complètes sur les paramètres de requête et d'autres fonctionnalités.
Dépôt GitHub FastAPI : Consultez le dépôt GitHub FastAPI pour le code source, les exemples et les contributions de la communauté.
Tutoriels FastAPI : Recherchez des tutoriels et des cours en ligne axés sur FastAPI pour approfondir vos connaissances et vos compétences.

En suivant ces meilleures pratiques et techniques pour les paramètres de requête FastAPI, vous pouvez créer des API robustes et efficaces qui répondent aux besoins de vos utilisateurs en 2024 et au-delà.

button