Création d'une API avec FastAPI

API est l'abréviation de Application Programming Interface (interface de programmation d'applications).
Une API est un intermédiaire logiciel qui permet à deux applications de communiquer entre elles.

Une API reçoit une requête d'une application et l'envoie à un serveur.
Le serveur traite ensuite la demande et renvoie les données à l'application. L'application interprète ensuite les données et les présente à l'utilisateur.

Ce mini-projet consiste à créer une API utilisant le framework Python FastAPI. Elle interagit avec des services gouvernementaux français comme :

  • API Addok : recherche d'adresses
  • API CatNat : informations sur les catastrophes naturelles

Pourquoi le framework FastAPI ?

FastAPI est un framework web performant pour la construction d'API avec Python 3.7+, basé sur les indices de type standard de Python.
Il aide les développeurs à créer des applications rapidement et efficacement.

Performance élevée :

  • Construit sur Starlette et Pydantic, il offre des performances proches de celles d'outils comme Node.js et Go.
  • Il est déal pour des applications nécessitant des réponses rapides, comme les appels API.
  • Starlette est un framework léger et asynchrone pour développer des applications web en Python.
    Il se concentre sur les performances et la modularité, tout en respectant le standard ASGI (Asynchronous Server Gateway Interface).
  • Pydanticest une bibliothèque Python utilisée pour la validation et la gestion des données structurées.
    Elle se base sur les annotations de type Python et offre une validation automatique des données d'entrée et de sortie.

Documentation automatique :

  • Documentation interactive générée automatiquement à partir des types Python (OpenAPI et Swagger UI).
  • Accessible via /docs.
  • OpenAPI est une spécification standardisée pour décrire des APIs REST.
  • Swagger UI est une interface utilisateur interactive permettant d'explorer, de tester et de documenter des APIs en utilisant la spécification OpenAPI.

Gestion des données structurées :

  • Les modèles basés sur Pydantic assurent une validation stricte des entrées et des sorties JSON.

Middleware intégré :

  • Par exemple, le middleware CORS (Cross-Origin Resource Sharing) est configuré pour permettre l'accès depuis d'autres domaines.

Exemple d'API

1. Sources :

Dans cet exemple, nous illustrons la construction d'une API simple avec FastAPI.
Vous pouvez la tester dans une application en suivant ce lien: mon Api géorisque

Le code source est accessible via le lien Github : Construire une API CatNat avec FastAPI

2. Explications :

Cette Api met en œuvre trois endpoints principaux.

  • / :
    Retourne un message de bienvenue. Parfait pour vérifier si l'API est opérationnelle.
  • /api/v1/{adresse} :
    Cet endpoint prend une chaîne représentant une adresse comme paramètre d'entrée. Voici son fonctionnement :
    • Envoie une requête à l'API Addok pour obtenir des suggestions d'adresses.
    • Pour chaque suggestion, crée une instance de Location.
    • Retourne une liste d'adresses pertinentes accompagnées de leurs coordonnées GPS.
  • /api/v1/catnat/ :
    Utilise l'API CatNat pour récupérer des informations sur les risques naturels (par exemple, inondations ou séismes).
    Les données retournées proviennent de l'API gouvernementale.

3. Résumé :

Les principales fonctionnalités de ce projet sont encapsulées dans deux fichiers :

  • models.py : Structure les données des adresses sous forme d'objets pour simplifier leur manipulation.
  • main.py : Orchestration des interactions entre l'utilisateur, les APIs externes (Addok et CatNat), et le modèle Location.

Cette application est particulièrement utile pour :

  • Rechercher des adresses via l'API Addok.
  • Obtenir des données détaillées sur les risques naturels liés à une localisation, grâce à l'API CatNat.

Fonctionnalités de l'API

1. Recherche d'adresses avec l'API Addok :

  • Endpoint : /api/v1/{adresse}
  • Description : Envoie une requête à l'API publique Addok pour rechercher des adresses.
    Retourne des informations enrichies (latitude, longitude, score, ville, code postal, etc.).
  • Utilisation typique : GET /api/v1/8 bd du port
    Réponse JSON structurée avec les coordonnées et détails de l'adresse.

2. Recherche des événements CatNat :

  • Endpoint : /api/v1/catnat/
  • Description : Interroge l'API Géorisques pour obtenir des informations sur les catastrophes naturelles dans un rayon défini autour d'une position géographique.
    Retourne une liste d'événements (type, date, gravité, etc.).
  • Utilisation typique : GET /api/v1/catnat/?longitude=2.3522&latitude=48.8566&rayon=1000
    Réponse contenant les événements trouvés pour les coordonnées fournies.

Valeur ajoutée de l’API

1. Centralisation des données :

Les utilisateurs accèdent à des informations variées (adresses, catastrophes naturelles, inondations, risques sismiques, cavités) via une seule API, simplifiant l'intégration des services..

2. Utilisation des données publiques :

Les données issues des services Géorisques et d'autres APIs gouvernementales deviennent facilement exploitables.

3. Adaptabilité et extensibilité :

L'API est conçue pour intégrer facilement d'autres sources de données gouvernementales, ajoutant des fonctionnalités au besoin.

Quelques API Gouvernementales Françaises

API Addok (api-adresse.data.gouv.fr) :

  • Objectif : Fournir une recherche d'adresses et de géocodage à partir de textes.
  • Exemple : http://api-adresse.data.gouv.fr/search/?q=adresse
    Résultat : Liste des événements correspondant à une zone géographique donnée.

API CatNat (Géorisques - Ministère de la Transition écologique) :

  • Objectif : Fournir des informations sur les zones à risque et les événements de catastrophes naturelles.
  • Exemple : https://georisques.gouv.fr/api/v1/gaspar/catnat/?longitude=2.3522&latitude=48.8566&rayon=1000
    Résultat : Liste des événements correspondant à une zone géographique donnée.

API AZI (Aléa Zones Inondables) :

  • Objectif : Fournir des informations sur les zones présentant un risque d’inondation.
  • Exemple : https://georisques.gouv.fr/api/v1/azi
    Résultat : Aléa inondation, classe de risque, et détails par parcelle.

API Zonage Sismique :

  • Objectif : Fournir des informations sur la classification sismique des zones en France.
  • Exemple : https://georisques.gouv.fr/api/v1/zonage-sismique
    Résultat : Niveau de sismicité et description du zonage.

API Cavités :

  • Objectif : Recenser les cavités souterraines (naturelles ou anthropiques) pouvant présenter un risque pour la stabilité des sols.
  • Exemple : https://georisques.gouv.fr/api/v1/cavites
    Résultat : Liste des cavités recensées dans la zone, avec détails sur leur nature, origine, et risque associé.