Python - Fast API - Créez votre API JSON en Python en une minute

TLDR : une minute, c'est le temps qu'il vous faudra pour copier/coller le contenu de deux fichiers et lancer une commande Docker.

Ça paraît dingue, mais c'est VRAI. Il vous faudra juste une minute pour créer l'exemple ci-dessous : créer le répertoire de votre projet, créer deux fichiers et lancer deux commandes Docker et ... c'est fini.

En tant que programmeur PHP, quand j'ai pris le temps de lire un article de blog sur FastAPI, j'ai pensé Nodidju ! Ç' n'est nén pussibe (Bon sang ! Ce n'est pas possible).

Avec seulement deux fichiers, nous allons construire notre propre image Docker avec Python et FastAPI installés et coder notre application REST API. Pas plus de deux !

Impossible de ne pas essayer tout de suite et ... wow ... c'est VRAI !

Voici le résultat : rendez-vous sur http://127.0.0.1:82 et obtenez votre première réponse JSON.

http://127.0.0.1:82

Pourquoi ça fonctionne​

• main.py définit une route (/) avec deux lignes de Python — FastAPI transforme cette fonction en endpoint HTTP fonctionnel, sans aucune configuration de serveur à écrire.
• Le Dockerfile regroupe Python, FastAPI et votre code dans une seule image d'environ 184 Mo, donc il n'y a rien à installer sur votre host à part Docker lui-même.

Créer notre première API​

Comme toujours, nous allons construire un exemple complètement fonctionnel. Ça ne pourrait pas être plus simple ; vous allez voir.

Créez un dossier bidon et placez-vous dedans :

$ mkdir /tmp/fastapi && cd $_

Dans ce dossier, créez un nouveau fichier appelé Dockerfile avec le contenu suivant :

# We'll use the latest version of Python and the smaller image in size (i.e. `slim`)
FROM python:slim?

# We'll define the default folder in the image to /app
WORKDIR /app?

# The only dependency we need is fastapi
RUN pip install --no-cache-dir 'fastapi[standard]'?

# We need to copy our Python script in the image
COPY main.py main.py?

# And we'll run FastAPI and call our script. We'll expose the script on port 82
CMD ["fastapi", "run", "main.py", "--port", "82"]

La taille finale de l'image sera d'environ 184 Mo, c'est-à-dire presque rien.

Comme vous l'avez vu, il nous faut un fichier appelé main.py ; créons-le :

from fastapi import FastAPI

app = FastAPI()?

@app.get("/")?
def read_root():
    return {"Hello": "World"}?

Ce code très simple définit une route appelée /. C'est une méthode GET et nous allons retourner un objet JSON :

{
  "Hello": "World"
}

Vous savez quoi ? C'est déjà terminé.

Lancer notre API​

Il nous faut construire notre image Docker et la lancer :

$ docker build -t python-fastapi . && docker run -p 82:82 python-fastapi▋

Une fois fait, rendez-vous sur http://127.0.0.1:82 et vous obtiendrez la même réponse JSON que celle montrée en haut de cet article ; dingue non ?

Documentation automatisée de votre API​

Et ce n'est que le début : FastAPI fournit une API auto-documentée basée sur le schéma OpenAPI. Ce schéma n'est pas seulement de la documentation : il peut aussi être linté, voir Validez votre schéma OpenAPI face aux standards REST Belgif.

Rendez-vous sur http://127.0.0.1:82/docs et vous le verrez en action :

http://127.0.0.1:82/docs

Il existe un second template, alternatif, appelé ReDoc. Vous pouvez y accéder via l'endpoint redoc, c'est-à-dire http://127.0.0.1:82/redoc :

http://127.0.0.1:82/redoc

Amusons-nous - Créer un générateur de blagues​

Nous allons construire un script générateur de blagues. Notre objectif : obtenir une blague au hasard ou une blague précise (du genre Donne-moi la troisième blague que tu connais).

Pour cela, nous allons mettre à jour notre script main.py et, comme nous ferons probablement plus d'une modification, nous allons monter notre dossier de l'host dans le container.

Pourquoi ? Monter notre dossier dans le container nous permettra de modifier le script et de simplement rafraîchir la page web pour voir le changement.

La seule chose à faire est de lancer notre container comme ceci : docker run -v .:/app -p 82:82 python-fastapi ... mais ça n'a pas fonctionné comme prévu.

Recréer l'image Docker pour le hot reload (passez cette étape si docker run -v .:/app rafraîchissait déjà chez vous)​

Arrêtez d'abord le container en cours d'exécution : retournez dans votre console et appuyez sur CTRL+C pour arrêter le container. Nous allons aussi supprimer le container. Vous pouvez le faire depuis Docker Desktop : cliquez sur le menu Containers et tuez votre container Python - Fastapi. Supprimez aussi l'image appelée python-fastapi.

Si vous préférez la ligne de commande, vous pouvez obtenir le même résultat en lançant ces deux commandes :

$ docker rm $(docker ps -aq --filter "ancestor=python-fastapi")
$ docker rmi python-fastapi --force▋

Maintenant, copiez/collez le contenu suivant dans votre Dockerfile existant :

# We'll use the latest version of Python and the smaller image in size (i.e. `slim`)
FROM python:slim?

# We'll define the default folder in the image to /app
WORKDIR /app?

# The only dependency we need is fastapi
RUN pip install --no-cache-dir 'fastapi[standard]'?

# We need to copy our Python script in the image
COPY main.py main.py?

// highlight-start
# Run Uvicorn with hot reload so any changes to our main.py script will force
# the server to invalidate the cache and refresh the page.
CMD ["uvicorn", "main:app", "--reload", "--host", "0.0.0.0", "--port", "82"]?
// highlight-end

Reconstruisez l'image et lancez un nouveau container, cette fois avec un volume, en exécutant ces commandes :

$ docker build -t python-fastapi . && docker run -v .:/app -p 82:82 python-fastapi▋

Nous avons maintenant une image Docker avec hot reload et nous avons monté notre dossier dans le container.

Modifiez votre script main.py comme ceci :

from fastapi import FastAPI

app = FastAPI()?

@app.get("/")?
def read_root():?
    # highlight-next-line
    return {"Hello": "Belgium!"}

Rafraîchissez votre page web, vous verrez Hello Belgium!. Modifiez votre main.py et remplacez Belgium! par France. Rechargez votre page web ; vous verrez Hello France. Super, nous avons un hot reload et nous pouvons vraiment commencer à jouer.

Notre générateur de blagues​

Nous allons mettre à jour notre script main.py comme ceci :

// highlight-next-line
from random import choice?
from fastapi import FastAPI

app = FastAPI()

// highlight-start
jokes = [?
    "Why do programmers always mix up Halloween and Christmas? Because Oct 31 == Dec 25",
    "Why don't programmers like nature? Because it's full of bugs!",
    "How many programmers does it take to change a light bulb? None. That's a hardware problem.",
    "What do you call 8 hobbits? A hobbyte",
    "What is this [“hip”, ”hip”]? hip hip array!"
]

@app.get("/jokes")?
async def get_jokes():?
    """
    Returns a random joke from the list.
    """
    return {"joke": choice(jokes)}?

@app.get("/jokes/{joke_id}")?
def read_item(joke_id: int):?
    """
    Returns a specific joke (between 0 and 4).
    """
    try:
        return {"joke": jokes[joke_id]}?
    except IndexError:?
        return {"error": f"Joke with ID {joke_id} not found."}, 404?
// highlight-end

Vous le voyez immédiatement, je pense :

• j'ai défini un tableau avec cinq blagues, codées en dur ;
• j'ai défini une nouvelle route appelée /jokes qui affichera une blague au hasard ;
• et enfin j'ai défini une route jokes/{joke_id} pour pouvoir viser une blague précise (comme « Donne-moi la deuxième blague que tu connais »).

Retournez dans votre navigateur et rendez-vous sur l'endpoint jokes (http://127.0.0.1:82/jokes) et, hop, vous avez une blague au hasard.

http://127.0.0.1:82/jokes

Rafraîchissez la page ; encore et encore. Chaque fois vous obtiendrez une blague au hasard (parmi une liste de 5).

Si vous en voulez une précise, ajoutez simplement un ID après, comme http://127.0.0.1:82/jokes/1

http://127.0.0.1:82/jokes/1

Nos endpoints jokes sont documentés automatiquement​

Et en revenant à la documentation (http://127.0.0.1:82/docs), nous avons maintenant trois routes et, regardez, la docstring Python est utilisée pour décrire la route.

http://127.0.0.1:82/docs

Vraiment, vraiment impressionnant !

Découvrir FastAPI​

N'attendez plus, allez sur https://fastapi.tiangolo.com/ pour voir plus d'exemples.

Et avant de publier votre API au monde entier, prenez cinq minutes pour lire API REST - Comment écrire de bonnes API : nommer correctement vos endpoints et choisir correctement vos codes de statut HTTP ne coûte rien le premier jour et coûte très cher le centième.

Lisez aussi le long tutoriel sur Real Python - Using FastAPI to Build Python Web APIs.