Skip to content

Chapitre 3.2 : Création du premier endpoint d'API

Temps d'étude : 30 minutes


1. Endpoint : Le port d'amarrage des données

Imaginez que notre API est une station spatiale. Un endpoint (point d'extrémité) est un port d'amarrage spécifique, conçu pour un certain type de vaisseaux.

  • Port N°1 — pour les cargos (données sur les planètes).
  • Port N°2 — pour les sondes d'exploration (données sur les missions).
  • Port N°3 — pour les navettes de passagers (données sur les astronautes).

Chaque endpoint est une URL unique qui est responsable d'une opération spécifique avec une ressource particulière.

💡 Analogie spatiale : GET /spaceships — c'est la commande "Centre de Contrôle → Station : Rapportez la liste de tous les vaisseaux amarrés". Cet endpoint renvoie une collection de ressources.


2. Création de la "flotte spatiale"

Pour l'instant, nous n'avons pas de base de données, nous allons donc créer une "simulation" — une simple liste de vaisseaux spatiaux sous forme de dictionnaire Python.

Ouvrez main.py et ajoutez ce code avant la définition de app :

# main.py

# Étape 1 : Création d'une simulation de base de données
db_spaceships = {
    1: {
        "name": "Voyager-1",
        "type": "Зонд",
        "launch_year": 1977,
        "status": "Активен"
    },
    2: {
        "name": "Hubble Space Telescope",
        "type": "Телескоп",
        "launch_year": 1990,
        "status": "Активен"
    },
    3: {
        "name": "ISS",
        "type": "Станция",
        "launch_year": 1998,
        "status": "На орбите"
    }
}

# ... ici le code app = FastAPI()
C'est notre "registre des vaisseaux spatiaux" avec lequel nous allons travailler.


3. Premier endpoint : Liste des vaisseaux

Nous allons maintenant créer un endpoint qui renverra l'ensemble de notre flotte.

Ajoutez ce code dans main.py après @app.get("/") :

# main.py

# ... code avec db_spaceships, FastAPI, app et read_root() ...

@app.get("/spaceships")
def get_spaceships():
    """
    Renvoie la liste de tous les vaisseaux spatiaux enregistrés.
    """
    return db_spaceships

  • @app.get("/spaceships") : Nous avons créé une nouvelle route. Désormais, les requêtes GET vers l'URL /spaceships seront gérées par la fonction get_spaceships.
  • return db_spaceships : FastAPI convertit automatiquement le dictionnaire Python en une réponse JSON valide.

4. Vérification du fonctionnement du nouveau port d'amarrage

Si votre serveur uvicorn est toujours en cours d'exécution avec le drapeau --reload, il s'est déjà rechargé et est prêt à fonctionner. Sinon, relancez-le :

uvicorn main:app --reload

Étape 1 : Vérification dans le navigateur

Ouvrez l'adresse http://127.0.0.1:8000/spaceships dans votre navigateur. Vous devriez voir la liste complète de vos vaisseaux au format JSON :

{
  "1": {
    "name": "Voyager-1",
    "type": "Зонд",
    "launch_year": 1977,
    "status": "Активен"
  },
  "2": {
    "name": "Hubble Space Telescope",
    "type": "Телескоп",
    "launch_year": 1990,
    "status": "Активен"
  },
  "3": {
    "name": "ISS",
    "type": "Станция",
    "launch_year": 1998,
    "status": "На орбите"
  }
}

Étape 2 : Vérification dans la documentation automatique

Rendez-vous sur http://127.0.0.1:8000/docs. Vous verrez qu'une nouvelle section est apparue dans la documentation pour l'endpoint GET /spaceships. Vous pouvez cliquer sur "Try it out" et "Execute" pour le tester directement de là !


5. Endpoint avec paramètre : Données sur un vaisseau spécifique

Et si nous n'avons besoin des données que sur le "Voyager-1" ? Pour cela, nous allons créer un endpoint avec un paramètre de chemin (path parameter).

Ajoutez ce code dans main.py :

# main.py

# ... le reste du code ...

@app.get("/spaceships/{ship_id}")
def get_spaceship(ship_id: int):
    """
    Renvoie les données d'un vaisseau spatial spécifique par son ID.
    """
    return db_spaceships.get(ship_id)

  • "/spaceships/{ship_id}" : Les accolades {} indiquent à FastAPI que ship_id est une variable qui sera transmise depuis l'URL.
  • ship_id: int : C'est une indication de type (type hint). FastAPI vérifiera automatiquement que l'ID transmis est un nombre entier. Si quelqu'un demande /spaceships/voyager, FastAPI renverra une erreur de validation 422 Unprocessable Entity. C'est de la magie !

Vérification :

Ouvrez http://127.0.0.1:8000/spaceships/2. Vous devriez obtenir uniquement les données du télescope "Hubble". Et si vous ouvrez http://127.0.0.1:8000/spaceships/99, vous obtiendrez null, car ce vaisseau n'existe pas.


Quiz pour la consolidation

1. Un endpoint dans une API est...

2. Que fait le décorateur `@app.get("/users")` ?

3. Que signifie l'écriture `"/items/{item_id}"` dans le chemin ?

4. Pourquoi l'indication de type `ship_id: int` est-elle nécessaire dans la fonction ?

5. Si vous demandez `/spaceships/abc` et que FastAPI attend un `int`, que se passera-t-il ?


🚀 Résumé du chapitre :

Vous avez créé avec succès deux "ports d'amarrage" sur votre station spatiale API :

  • 🛰️ Un pour obtenir la liste de tous les vaisseaux (/spaceships)
  • 🔭 Le second pour obtenir les données d'un appareil spécifique (/spaceships/{ship_id})

Vous avez également découvert la puissance de la validation automatique des types de FastAPI, qui protège votre API contre les requêtes incorrectes.

Le système de navigation est configuré ! Dans le prochain chapitre, nous allons créer les "plans" de nos vaisseaux spatiaux à l'aide de Pydantic, afin de rendre notre API encore plus intelligente et fiable.

📌 Vérification :

  • Le serveur uvicorn est lancé et fonctionne.
  • L'URL http://127.0.0.1:8000/spaceships renvoie un JSON avec la liste des vaisseaux.
  • L'URL http://127.0.0.1:8000/spaceships/1 renvoie les données du "Voyager-1".
  • L'URL http://127.0.0.1:8000/docs affiche deux nouveaux endpoints.

⚠️ En cas d'erreurs :

  • 404 Not Found : Vérifiez si l'URL est correctement écrite dans le navigateur et dans le décorateur @app.get(...).
  • Erreur de code : Vérifiez attentivement la syntaxe, en particulier l'indentation en Python et les virgules dans le dictionnaire.