Quand j’ai commencé à enseigner les API REST à mes étudiants en BTS SIO, je voyais souvent la même réaction : un mélange de curiosité et d’appréhension. Le terme « API REST » semble technique, presque intimidant. Pourtant, vous utilisez des API REST chaque jour sans le savoir, que ce soit en consultant la météo sur votre téléphone, en scrollant vos réseaux sociaux ou en effectuant un paiement en ligne.

Aujourd’hui, je vais vous accompagner pas à pas pour comprendre ce qu’est une API REST et surtout pour en créer une vous-même en Python. À la fin de cet article, vous aurez un projet fonctionnel que vous pourrez présenter en épreuve E4 ou intégrer à votre portfolio. Pas besoin d’être un expert : si vous savez écrire une fonction Python, vous avez déjà les bases nécessaires.

Qu’est-ce qu’une API REST et pourquoi c’est incontournable

Une API (Application Programming Interface) est un ensemble de règles qui permet à deux logiciels de communiquer entre eux. Pensez-y comme un serveur dans un restaurant : vous (le client) passez votre commande, le serveur (l’API) transmet votre demande à la cuisine (le serveur back-end), puis vous rapporte votre plat (la réponse).

REST (Representational State Transfer) est un style d’architecture défini par Roy Fielding en 2000 dans sa thèse doctorale. Ce n’est pas un protocole strict, mais un ensemble de contraintes qui rendent les API prévisibles, scalables et faciles à maintenir. Concrètement, une API REST utilise le protocole HTTP pour permettre à un client d’effectuer des opérations sur des ressources identifiées par des URL.

En 2026, les API REST restent le standard dominant dans le développement web. Selon le rapport State of API de Postman, plus de 86 % des développeurs utilisent des API REST dans leurs projets. Que vous vous orientiez vers le développement web, le DevOps ou même la cybersécurité, maîtriser les API REST est devenu une compétence fondamentale.

Pour les étudiants en BTS SIO, c’est d’autant plus important : l’épreuve E4 valorise les projets qui démontrent une architecture client-serveur. Créer votre propre API est un excellent moyen de montrer cette compétence. Si vous cherchez d’autres projets Python pour enrichir votre portfolio, une API REST constitue un point de départ idéal.

Les principes fondamentaux d’une API RESTful

Avant d’écrire la moindre ligne de code, je tiens à ce que vous compreniez les concepts clés. C’est ce qui fera la différence entre un développeur qui copie du code et un développeur qui comprend ce qu’il fait.

Les méthodes HTTP (verbes CRUD)

REST s’appuie sur les méthodes HTTP standard pour définir les actions sur les ressources :

Les codes de statut HTTP

Chaque réponse de votre API doit inclure un code de statut qui indique au client si sa requête a réussi ou échoué :

• 200 OK : la requête a réussi (GET, PUT)
• 201 Created : une nouvelle ressource a été créée (POST)
• 204 No Content : succès sans contenu retourné (DELETE)
• 400 Bad Request : la requête est mal formée
• 404 Not Found : la ressource demandée n’existe pas
• 500 Internal Server Error : erreur côté serveur

Le format JSON

Les API REST échangent des données au format JSON (JavaScript Object Notation). C’est un format léger, lisible par les humains et facile à parser par les machines. Voici un exemple de réponse JSON :

{
  "id": 1,
  "nom": "Dupont",
  "prenom": "Marie",
  "option": "SLAM",
  "annee": 2
}

Les principes REST à respecter

Pour qu’une API soit considérée comme RESTful, elle doit respecter plusieurs contraintes : être sans état (stateless, chaque requête contient toutes les informations nécessaires), avoir une interface uniforme (URLs cohérentes et prévisibles), et séparer clairement le client du serveur. Ces principes garantissent une API maintenable et évolutive.

Flask ou FastAPI : choisir le bon framework Python

Python offre plusieurs frameworks pour créer des API REST. Les deux plus populaires sont Flask et FastAPI. Je vais vous présenter les deux car chacun a ses atouts. Dans mes cours, je commence souvent par Flask pour sa simplicité, puis j’introduis FastAPI pour ses fonctionnalités avancées.

Flask : la simplicité avant tout

Flask est un micro-framework créé en 2010. Son approche minimaliste le rend parfait pour l’apprentissage. Il ne vous impose rien : vous ajoutez les extensions dont vous avez besoin, quand vous en avez besoin. Pour installer Flask, une seule commande suffit :

pip install flask

FastAPI : la modernité et la performance

FastAPI, créé par Sebastián Ramírez en 2018, est devenu le framework Python à la croissance la plus rapide. Il utilise les type hints de Python pour valider automatiquement les données et génère une documentation interactive Swagger sans effort supplémentaire. Son installation est tout aussi simple :

pip install fastapi uvicorn

Pour choisir entre les deux, voici ma recommandation : si vous débutez complètement, commencez par Flask. Si vous êtes à l’aise avec les type hints Python et que vous voulez un outil plus moderne, allez directement vers FastAPI. Dans les deux cas, les concepts REST restent identiques. Un bon éditeur de code comme VS Code facilitera grandement votre développement, quel que soit le framework choisi.

Créer sa première API REST avec Flask

Passons à la pratique. Je vais vous guider pour créer une API REST complète avec Flask en partant de zéro. Ouvrez votre éditeur VS Code et suivez chaque étape.

Étape 1 : préparer l’environnement

Commencez par créer un environnement virtuel pour isoler les dépendances de votre projet. C’est une bonne habitude à prendre dès maintenant :

# Créer un dossier pour le projet
mkdir mon-api-rest
cd mon-api-rest

# Créer et activer l'environnement virtuel
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# Installer Flask
pip install flask

Si vous travaillez sous Linux, ces commandes de base vous seront familières.

Étape 2 : créer l’API minimale

Créez un fichier app.py avec le code suivant. Je commente chaque ligne pour que vous compreniez exactement ce qui se passe :

from flask import Flask, jsonify, request

app = Flask(__name__)

# Base de données simulée (liste en mémoire)
etudiants = [
    {"id": 1, "nom": "Dupont", "prenom": "Marie", "option": "SLAM"},
    {"id": 2, "nom": "Martin", "prenom": "Lucas", "option": "SISR"},
    {"id": 3, "nom": "Bernard", "prenom": "Sophie", "option": "SLAM"}
]

# GET : récupérer tous les étudiants
@app.route('/api/etudiants', methods=['GET'])
def get_etudiants():
    return jsonify(etudiants), 200

# GET : récupérer un étudiant par son id
@app.route('/api/etudiants/<int:id>', methods=['GET'])
def get_etudiant(id):
    etudiant = next((e for e in etudiants if e["id"] == id), None)
    if etudiant is None:
        return jsonify({"erreur": "Étudiant non trouvé"}), 404
    return jsonify(etudiant), 200

# POST : ajouter un étudiant
@app.route('/api/etudiants', methods=['POST'])
def ajouter_etudiant():
    donnees = request.get_json()
    nouvel_etudiant = {
        "id": len(etudiants) + 1,
        "nom": donnees["nom"],
        "prenom": donnees["prenom"],
        "option": donnees["option"]
    }
    etudiants.append(nouvel_etudiant)
    return jsonify(nouvel_etudiant), 201

# PUT : modifier un étudiant
@app.route('/api/etudiants/<int:id>', methods=['PUT'])
def modifier_etudiant(id):
    etudiant = next((e for e in etudiants if e["id"] == id), None)
    if etudiant is None:
        return jsonify({"erreur": "Étudiant non trouvé"}), 404
    donnees = request.get_json()
    etudiant.update(donnees)
    return jsonify(etudiant), 200

# DELETE : supprimer un étudiant
@app.route('/api/etudiants/<int:id>', methods=['DELETE'])
def supprimer_etudiant(id):
    global etudiants
    etudiant = next((e for e in etudiants if e["id"] == id), None)
    if etudiant is None:
        return jsonify({"erreur": "Étudiant non trouvé"}), 404
    etudiants = [e for e in etudiants if e["id"] != id]
    return jsonify({"message": "Étudiant supprimé"}), 200

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Étape 3 : lancer et tester

Lancez votre API avec la commande :

python app.py

Votre API est maintenant accessible sur http://localhost:5000. Ouvrez un nouveau terminal et testez avec curl :

# Récupérer tous les étudiants
curl http://localhost:5000/api/etudiants

# Ajouter un étudiant
curl -X POST http://localhost:5000/api/etudiants \
  -H "Content-Type: application/json" \
  -d '{"nom": "Leroy", "prenom": "Emma", "option": "SLAM"}'

En moins de 30 lignes de code utile, vous avez une API REST fonctionnelle avec les quatre opérations CRUD. C’est la puissance de Flask.

Construire une API plus robuste avec FastAPI

Maintenant que vous maîtrisez les bases avec Flask, voyons comment FastAPI apporte un niveau supérieur de validation et de documentation automatique. C’est le framework que je recommande pour les projets plus ambitieux.

L’équivalent FastAPI

Voici la même API recodée avec FastAPI. Notez l’utilisation des modèles Pydantic pour la validation :

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional

app = FastAPI(title="API Étudiants BTS SIO")

# Modèle de données avec validation automatique
class Etudiant(BaseModel):
    nom: str
    prenom: str
    option: str

class EtudiantResponse(Etudiant):
    id: int

# Base de données simulée
etudiants_db: dict[int, dict] = {
    1: {"id": 1, "nom": "Dupont", "prenom": "Marie", "option": "SLAM"},
    2: {"id": 2, "nom": "Martin", "prenom": "Lucas", "option": "SISR"}
}
compteur_id = 3

@app.get("/api/etudiants", response_model=list[EtudiantResponse])
def lister_etudiants():
    return list(etudiants_db.values())

@app.get("/api/etudiants/{id}", response_model=EtudiantResponse)
def obtenir_etudiant(id: int):
    if id not in etudiants_db:
        raise HTTPException(status_code=404, detail="Étudiant non trouvé")
    return etudiants_db[id]

@app.post("/api/etudiants", response_model=EtudiantResponse, status_code=201)
def creer_etudiant(etudiant: Etudiant):
    global compteur_id
    nouvel_etudiant = {"id": compteur_id, **etudiant.model_dump()}
    etudiants_db[compteur_id] = nouvel_etudiant
    compteur_id += 1
    return nouvel_etudiant

@app.put("/api/etudiants/{id}", response_model=EtudiantResponse)
def modifier_etudiant(id: int, etudiant: Etudiant):
    if id not in etudiants_db:
        raise HTTPException(status_code=404, detail="Étudiant non trouvé")
    etudiants_db[id] = {"id": id, **etudiant.model_dump()}
    return etudiants_db[id]

@app.delete("/api/etudiants/{id}")
def supprimer_etudiant(id: int):
    if id not in etudiants_db:
        raise HTTPException(status_code=404, detail="Étudiant non trouvé")
    del etudiants_db[id]
    return {"message": "Étudiant supprimé"}

Pour lancer cette API :

uvicorn app:app --reload --port 8000

La documentation automatique Swagger

L’un des atouts majeurs de FastAPI est sa documentation interactive générée automatiquement. Dès que votre serveur tourne, rendez-vous sur http://localhost:8000/docs pour accéder à l’interface Swagger UI. Vous pouvez y tester chaque endpoint directement depuis votre navigateur, sans outil externe. C’est un gain de temps considérable, surtout quand vous travaillez en équipe ou que vous présentez votre projet.

FastAPI génère également une documentation alternative au format ReDoc sur http://localhost:8000/redoc, parfaite pour la présentation en épreuve E4.

Tester et débugger son API efficacement

Une API sans tests, c’est comme du code sans versionnement Git : ça fonctionne jusqu’au jour où ça casse. Voici les outils et méthodes que j’utilise en cours pour tester les API.

Tester avec curl en ligne de commande

Curl est l’outil le plus rapide pour tester une API. Voici les commandes essentielles :

# GET : lister toutes les ressources
curl -s http://localhost:5000/api/etudiants | python -m json.tool

# POST : créer une ressource
curl -X POST http://localhost:5000/api/etudiants \
  -H "Content-Type: application/json" \
  -d '{"nom": "Petit", "prenom": "Jean", "option": "SISR"}'

# PUT : modifier une ressource
curl -X PUT http://localhost:5000/api/etudiants/1 \
  -H "Content-Type: application/json" \
  -d '{"nom": "Dupont", "prenom": "Marie", "option": "SISR"}'

# DELETE : supprimer une ressource
curl -X DELETE http://localhost:5000/api/etudiants/2

Tester avec Postman

Postman est une application graphique qui simplifie énormément le test d’API. Elle permet de sauvegarder des collections de requêtes, de définir des variables d’environnement et même d’automatiser des scénarios de test. C’est l’outil que je recommande à mes étudiants pour leur travail quotidien, et il fait partie des outils indispensables pour tout étudiant en informatique.

Écrire des tests automatisés avec pytest

Pour un projet sérieux, les tests manuels ne suffisent pas. Voici comment écrire des tests automatisés pour votre API Flask :

import pytest
from app import app

@pytest.fixture
def client():
    app.config['TESTING'] = True
    with app.test_client() as client:
        yield client

def test_get_etudiants(client):
    response = client.get('/api/etudiants')
    assert response.status_code == 200
    data = response.get_json()
    assert len(data) >= 1

def test_creer_etudiant(client):
    nouveau = {"nom": "Test", "prenom": "User", "option": "SLAM"}
    response = client.post('/api/etudiants', json=nouveau)
    assert response.status_code == 201
    data = response.get_json()
    assert data["nom"] == "Test"

def test_etudiant_inexistant(client):
    response = client.get('/api/etudiants/999')
    assert response.status_code == 404

Lancez les tests avec pytest -v. Si tous les voyants sont au vert, votre API est solide.

Bonnes pratiques et sécurité pour une API en production

Créer une API qui fonctionne en local est une chose. La rendre sécurisée et professionnelle en est une autre. Voici les points essentiels que j’enseigne à mes étudiants avant tout déploiement. Ces notions sont d’ailleurs valorisées en veille technologique BTS SIO et dans les rapports de stage.

Valider les données entrantes

Ne faites jamais confiance aux données envoyées par le client. Avec FastAPI, la validation est automatique grâce aux modèles Pydantic. Avec Flask, vous devez la coder manuellement :

@app.route('/api/etudiants', methods=['POST'])
def ajouter_etudiant():
    donnees = request.get_json()
    if not donnees:
        return jsonify({"erreur": "Corps de requête vide"}), 400
    champs_requis = ["nom", "prenom", "option"]
    for champ in champs_requis:
        if champ not in donnees:
            return jsonify({"erreur": f"Champ '{champ}' manquant"}), 400
    if donnees["option"] not in ["SLAM", "SISR"]:
        return jsonify({"erreur": "Option invalide (SLAM ou SISR)"}), 400
    # ... suite du traitement

Implémenter l’authentification

Pour protéger votre API, l’approche la plus courante est l’utilisation de tokens JWT (JSON Web Tokens). Le client s’authentifie une première fois avec ses identifiants, reçoit un token, puis l’inclut dans l’en-tête de chaque requête suivante. C’est un sujet à part entière que je développerai dans un prochain article, mais sachez que les bibliothèques flask-jwt-extended et python-jose simplifient grandement l’implémentation.

Gérer le CORS

Si votre front-end (React, Vue.js) est hébergé sur un domaine différent de votre API, vous devrez configurer le CORS (Cross-Origin Resource Sharing). Avec Flask :

pip install flask-cors

from flask_cors import CORS
app = Flask(__name__)
CORS(app, resources={r"/api/*": {"origins": "http://localhost:3000"}})

Versionner son API

Préfixez toujours vos routes avec un numéro de version : /api/v1/etudiants. Cela vous permettra de faire évoluer votre API sans casser les clients existants. C’est une pratique standard dans l’industrie que vous retrouverez dans toutes les API publiques (GitHub, Stripe, Twitter).

Projet complet : une API CRUD de gestion d’étudiants

Pour consolider tout ce que nous avons vu, voici un projet complet qui utilise une vraie base de données SQLite au lieu d’une simple liste en mémoire. Ce projet est directement exploitable pour votre épreuve E4 ou votre portfolio GitHub Pages.

Structure du projet

api-etudiants/
├── app.py              # Point d'entrée de l'API
├── database.py         # Configuration de la base de données
├── models.py           # Modèles de données
├── requirements.txt    # Dépendances du projet
└── tests/
    └── test_api.py     # Tests automatisés

Le fichier database.py

import sqlite3
import os

DB_PATH = os.path.join(os.path.dirname(__file__), "etudiants.db")

def get_db():
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    return conn

def init_db():
    conn = get_db()
    conn.execute('''
        CREATE TABLE IF NOT EXISTS etudiants (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            nom TEXT NOT NULL,
            prenom TEXT NOT NULL,
            option_sio TEXT NOT NULL CHECK(option_sio IN ('SLAM', 'SISR')),
            annee INTEGER DEFAULT 1
        )
    ''')
    conn.commit()
    conn.close()

L’application principale app.py

from flask import Flask, jsonify, request
from database import get_db, init_db

app = Flask(__name__)

@app.before_request
def before_first_request():
    init_db()

@app.route('/api/v1/etudiants', methods=['GET'])
def lister_etudiants():
    conn = get_db()
    etudiants = conn.execute('SELECT * FROM etudiants').fetchall()
    conn.close()
    return jsonify([dict(e) for e in etudiants]), 200

@app.route('/api/v1/etudiants/<int:id>', methods=['GET'])
def obtenir_etudiant(id):
    conn = get_db()
    etudiant = conn.execute(
        'SELECT * FROM etudiants WHERE id = ?', (id,)
    ).fetchone()
    conn.close()
    if etudiant is None:
        return jsonify({"erreur": "Étudiant non trouvé"}), 404
    return jsonify(dict(etudiant)), 200

@app.route('/api/v1/etudiants', methods=['POST'])
def creer_etudiant():
    donnees = request.get_json()
    if not donnees:
        return jsonify({"erreur": "Données manquantes"}), 400
    for champ in ["nom", "prenom", "option_sio"]:
        if champ not in donnees:
            return jsonify({"erreur": f"Champ '{champ}' requis"}), 400
    conn = get_db()
    cursor = conn.execute(
        'INSERT INTO etudiants (nom, prenom, option_sio, annee) VALUES (?, ?, ?, ?)',
        (donnees["nom"], donnees["prenom"], donnees["option_sio"],
         donnees.get("annee", 1))
    )
    conn.commit()
    etudiant = conn.execute(
        'SELECT * FROM etudiants WHERE id = ?', (cursor.lastrowid,)
    ).fetchone()
    conn.close()
    return jsonify(dict(etudiant)), 201

@app.route('/api/v1/etudiants/<int:id>', methods=['PUT'])
def modifier_etudiant(id):
    conn = get_db()
    etudiant = conn.execute(
        'SELECT * FROM etudiants WHERE id = ?', (id,)
    ).fetchone()
    if etudiant is None:
        conn.close()
        return jsonify({"erreur": "Étudiant non trouvé"}), 404
    donnees = request.get_json()
    conn.execute(
        'UPDATE etudiants SET nom=?, prenom=?, option_sio=?, annee=? WHERE id=?',
        (donnees.get("nom", etudiant["nom"]),
         donnees.get("prenom", etudiant["prenom"]),
         donnees.get("option_sio", etudiant["option_sio"]),
         donnees.get("annee", etudiant["annee"]), id)
    )
    conn.commit()
    etudiant_maj = conn.execute(
        'SELECT * FROM etudiants WHERE id = ?', (id,)
    ).fetchone()
    conn.close()
    return jsonify(dict(etudiant_maj)), 200

@app.route('/api/v1/etudiants/<int:id>', methods=['DELETE'])
def supprimer_etudiant(id):
    conn = get_db()
    etudiant = conn.execute(
        'SELECT * FROM etudiants WHERE id = ?', (id,)
    ).fetchone()
    if etudiant is None:
        conn.close()
        return jsonify({"erreur": "Étudiant non trouvé"}), 404
    conn.execute('DELETE FROM etudiants WHERE id = ?', (id,))
    conn.commit()
    conn.close()
    return jsonify({"message": "Étudiant supprimé avec succès"}), 200

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Ce projet utilise des requêtes paramétrées (le ? dans les requêtes SQL) pour prévenir les injections SQL. C’est un réflexe de sécurité indispensable, surtout si vous étudiez la cybersécurité.

Notez l’utilisation du préfixe /api/v1/ dans toutes les routes, conformément à la bonne pratique de versionnement que nous avons vue plus haut. Vous pouvez suivre vos modifications avec les commandes Git au fur et à mesure de votre développement.

Pour aller plus loin avec ce projet, vous pourriez ajouter une interface front-end, déployer l’API sur un serveur Linux auto-hébergé, ou encore automatiser le déploiement avec Ansible. Ce sont autant de compétences valorisées dans le parcours d’un développeur en 2026.

Lucie Moreau

Formatrice IT indépendante depuis 2016, ancienne étudiante BTS SIO SLAM. 6 ans d'expérience en entreprise.