Concepts des API REST pour l'IA

Theorie 45 min

Qu'est-ce qu'une API ?

Une API (Application Programming Interface) est un contrat qui definit comment deux composants logiciels communiquent entre eux. Dans le contexte du deploiement d'IA, une API est le pont entre votre modele entraine et le monde exterieur — les applications, les utilisateurs et les autres services qui souhaitent consommer des predictions.

L'analogie du restaurant

La maniere la plus intuitive de comprendre une API est de penser a un restaurant :

Restaurant	Monde des API
Client	Application cliente (application web, application mobile, autre service)
Menu	Documentation de l'API (endpoints disponibles, entrees attendues)
Commande	Requete HTTP avec donnees d'entree (payload JSON)
Serveur	Serveur API (recoit les requetes, les route, retourne les reponses)
Cuisine	Modele ML (traite l'entree, genere la prediction)
Plat servi	Reponse HTTP avec les resultats de prediction
Addition	Code de statut de la reponse (200 OK, 400 Bad Request, etc.)

Point cle

Tout comme un serveur n'a pas besoin de savoir comment cuisiner, une API n'a pas besoin d'exposer le fonctionnement interne de votre modele. Le client a seulement besoin de savoir quoi envoyer et quoi attendre en retour.

Architecture REST

REST (Representational State Transfer) est un style architectural pour la conception d'applications en reseau. Une API REST suit un ensemble de contraintes qui la rendent evolutive, sans etat et facile a comprendre.

Principes REST

Principe	Description	Exemple API IA
Sans etat	Chaque requete contient toutes les informations necessaires pour la traiter	Chaque requete de prediction inclut l'ensemble complet des features d'entree
Client-Serveur	Separation entre le consommateur et le fournisseur	L'application web (client) est separee du serveur de modele
Interface uniforme	Methodes HTTP standard et conventions d'URI	`POST /api/v1/predict` pour les predictions
Base sur les ressources	Tout est une ressource identifiee par un URI	`/models`, `/predictions`, `/health`
Mise en cache	Les reponses peuvent etre mises en cache quand c'est pertinent	Mettre en cache les predictions repetees pour des entrees identiques
Systeme en couches	Le client ne peut pas savoir s'il est connecte directement ou via un intermediaire	Un repartiteur de charge se situe entre le client et l'API

Architecture d'API REST pour l'IA

Methodes HTTP

Les methodes HTTP definissent l'action que vous souhaitez effectuer sur une ressource. Pour les API d'IA, certaines methodes sont plus courantes que d'autres.

Methode	Action	Idempotent	Sure	Utilisation API IA
GET	Recuperer des donnees	✅ Oui	✅ Oui	Obtenir les infos du modele, verification de sante, lister les modeles disponibles
POST	Creer/Soumettre des donnees	❌ Non	❌ Non	Soumettre des features pour prediction, telecharger des donnees d'entrainement
PUT	Remplacer entierement	✅ Oui	❌ Non	Remplacer une version du modele
PATCH	Mise a jour partielle	❌ Non	❌ Non	Mettre a jour la configuration du modele
DELETE	Supprimer une ressource	✅ Oui	❌ Non	Supprimer un modele deploye

Endpoints API IA courants

GET    /api/v1/health              → Verifier si le service fonctionne
GET    /api/v1/models              → Lister les modeles disponibles
GET    /api/v1/models/{id}         → Obtenir les details d'un modele specifique
POST   /api/v1/predict             → Soumettre des features, recevoir une prediction
POST   /api/v1/predict/batch       → Soumettre plusieurs entrees pour prediction par lot
GET    /api/v1/predict/{id}        → Recuperer un resultat de prediction passe
DELETE /api/v1/models/{id}         → Supprimer un modele deploye

Pourquoi POST pour les predictions ?

Meme si une prediction ne "cree" pas une ressource au sens traditionnel, nous utilisons POST car :

Les features d'entree peuvent etre complexes (objets imbriques, tableaux) — trop volumineux pour les parametres d'URL
La requete a un corps (payload JSON)
Les predictions peuvent avoir des effets de bord (journalisation, facturation)

Codes de statut HTTP

Les codes de statut indiquent au client ce qui s'est passe avec sa requete. Ils sont regroupes par categorie.

Familles de codes de statut

Plage	Categorie	Signification
1xx	Informatif	Requete recue, traitement en cours
2xx	Succes	Requete traitee avec succes
3xx	Redirection	Action supplementaire requise
4xx	Erreur client	Probleme avec la requete
5xx	Erreur serveur	Probleme cote serveur

Codes de statut essentiels pour les API IA

Code	Nom	Quand l'utiliser	Exemple API IA
200	OK	Requete reussie	Prediction retournee avec succes
201	Created	Ressource creee	Nouveau modele telecharge et enregistre
204	No Content	Succes, pas de corps	Modele supprime avec succes
400	Bad Request	Format d'entree invalide	Erreur de syntaxe JSON dans le corps de la requete
401	Unauthorized	Authentification manquante	Pas de cle API fournie
403	Forbidden	Permissions insuffisantes	La cle API n'a pas acces aux predictions
404	Not Found	La ressource n'existe pas	ID du modele non trouve
422	Unprocessable Entity	Validation echouee	Valeurs des features hors de la plage attendue
429	Too Many Requests	Limite de debit depassee	Le client a envoye trop de requetes de prediction
500	Internal Server Error	Erreur serveur inattendue	Le modele a plante pendant l'inference
503	Service Unavailable	Serveur pas pret	Le modele est encore en cours de chargement au demarrage

422 vs 400

400 Bad Request : Le JSON lui-meme est malforme (erreur de syntaxe)
422 Unprocessable Entity : Le JSON est valide, mais les donnees ne passent pas la validation (ex. age negatif, champ obligatoire manquant)

FastAPI utilise 422 par defaut pour les erreurs de validation des modeles Pydantic.

Format JSON requete/reponse

Les API REST communiquent en utilisant JSON (JavaScript Object Notation). Pour les API d'IA, vous devez concevoir des schemas d'entree/sortie clairs.

Requete de prediction

{
  "features": {
    "age": 35,
    "income": 55000,
    "credit_score": 720,
    "employment_years": 8,
    "loan_amount": 25000
  },
  "options": {
    "explain": true,
    "threshold": 0.5
  }
}

Reponse de prediction

{
  "prediction": "approved",
  "probability": 0.87,
  "confidence": "high",
  "model_version": "loan-classifier-v2.1",
  "timestamp": "2026-02-23T14:30:00Z",
  "explanation": {
    "top_features": [
      {"feature": "credit_score", "importance": 0.42},
      {"feature": "income", "importance": 0.31},
      {"feature": "employment_years", "importance": 0.15}
    ]
  }
}

Reponse d'erreur

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input features",
    "details": [
      {
        "field": "age",
        "message": "Value must be between 18 and 120",
        "received": -5
      }
    ]
  },
  "timestamp": "2026-02-23T14:31:00Z",
  "request_id": "req_abc123"
}

Bonnes pratiques de conception d'API

1. Conventions de nommage des endpoints

Convention	Bon	Mauvais
Utiliser des noms, pas des verbes	`/api/v1/predictions`	`/api/v1/makePrediction`
Utiliser des noms au pluriel	`/api/v1/models`	`/api/v1/model`
Utiliser le kebab-case	`/api/v1/model-versions`	`/api/v1/modelVersions`
Versionner votre API	`/api/v1/predict`	`/predict`
Utiliser la hierarchie pour les relations	`/api/v1/models/{id}/predictions`	`/api/v1/model-predictions`

2. Validation des requetes

Validez toujours les donnees d'entree avant de les envoyer a votre modele :

from pydantic import BaseModel, Field, validator

class PredictionInput(BaseModel):
    age: int = Field(..., ge=18, le=120, description="Customer age")
    income: float = Field(..., gt=0, description="Annual income in USD")
    credit_score: int = Field(..., ge=300, le=850)

    @validator("income")
    def income_must_be_reasonable(cls, v):
        if v > 10_000_000:
            raise ValueError("Income seems unrealistically high")
        return v

Pourquoi valider ?

Empeche votre modele de recevoir des entrees absurdes
Retourne des messages d'erreur clairs aux clients
Evite les echecs silencieux (le modele retourne une prediction pour des donnees aberrantes)
Protege contre les attaques par injection

3. Format de reponse coherent

Retournez toujours les reponses dans une enveloppe coherente :

{
    "status": "success",      # or "error"
    "data": { ... },          # response payload
    "meta": {                 # metadata
        "model_version": "v2.1",
        "response_time_ms": 45,
        "request_id": "req_abc123"
    }
}

Authentification et securite

Proteger votre API d'IA est essentiel — vous ne voulez pas que des utilisateurs non autorises executent des predictions (ce qui consomme des ressources de calcul et peut acceder a des modeles sensibles).

Cles API

La methode d'authentification la plus simple. Le client inclut une cle secrete dans les en-tetes de la requete.

GET /api/v1/models HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_abc123def456

Avantages	Inconvenients
Simple a implementer	Pas d'expiration integree
Facile a utiliser pour les clients	Difficile de gerer les permissions par cle
Fonctionne pour le serveur-a-serveur	Vulnerable si expose dans le code cote client

JWT (JSON Web Tokens) — Apercu

JWT est un mecanisme d'authentification plus avance ou le serveur emet un jeton signe que le client inclut dans les requetes suivantes.

Un jeton JWT a trois parties : Header (algorithme), Payload (revendications/permissions) et Signature (verification).

Quand utiliser quoi ?

Cles API : Services internes simples, prototypage, serveur-a-serveur
JWT : Applications multi-utilisateurs, permissions granulaires, expiration de jeton necessaire
OAuth 2.0 : Acces tiers, autorisation deleguee

Lorsqu'une application web a https://myapp.com essaie d'appeler votre API a https://api.myml.com, le navigateur la bloque par defaut. Les en-tetes CORS indiquent au navigateur quelles origines sont autorisees.

Exemple de configuration CORS

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://myapp.com", "http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

Securite

N'utilisez jamais allow_origins=["*"] en production. Cela permet a n'importe quel site web d'appeler votre API, ce qui peut mener a des abus et des fuites de donnees.

Limitation du debit

La limitation du debit controle combien de requetes un client peut effectuer dans une fenetre de temps donnee. C'est essentiel pour les API d'IA car chaque prediction consomme des ressources de calcul (temps CPU/GPU, memoire).

Strategie	Description	Cas d'utilisation
Fenetre fixe	X requetes par minute/heure	Quotas simples par cle API
Fenetre glissante	Taux lisse sur une fenetre mobile	Empeche les abus par rafale
Seau a jetons	Autorise de courtes rafales jusqu'a une limite	API avec trafic variable
Par endpoint	Limites differentes par endpoint	`/predict` = 100/min, `/health` = illimite

Reponse de limitation du debit

Lorsqu'un client depasse la limite, retournez une reponse 429 Too Many Requests avec des en-tetes utiles :

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708700000

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded 100 requests per minute. Please retry after 30 seconds."
  }
}

REST vs GraphQL vs gRPC

Lors de la construction d'API d'IA, REST est le choix le plus courant, mais il vaut la peine de comprendre les alternatives.

Caracteristique	REST	GraphQL	gRPC
Protocole	HTTP/1.1 ou HTTP/2	HTTP/1.1 ou HTTP/2	HTTP/2
Format de donnees	JSON	JSON	Protocol Buffers (binaire)
Schema	OpenAPI (optionnel)	Obligatoire (SDL)	Obligatoire (.proto)
Courbe d'apprentissage	Faible	Moyenne	Elevee
Performance	Bonne	Bonne	Excellente
Support navigateur	Natif	Natif	Limite (necessite un proxy)
Streaming	Limite	Subscriptions	Bidirectionnel
Cas d'utilisation	API generales, web	Requetes flexibles, mobile	Microservices, faible latence
Pertinence IA	Le plus courant pour les API ML	Requetes multi-modeles complexes	Inference a haut debit

Pour ce cours

Nous nous concentrons sur les API REST car elles sont les plus largement utilisees, les plus faciles a tester et les mieux supportees par des outils comme Swagger et Postman. Si vous avez besoin d'inference a tres faible latence entre microservices, envisagez gRPC comme prochaine etape.

Le cycle de vie requete/reponse

Comprendre le cycle de vie complet d'une requete API vous aide a debugger les problemes et a optimiser les performances.

Resume

Concept	Point cle
API REST	Maniere standard d'exposer des modeles ML via HTTP
Methodes HTTP	POST pour les predictions, GET pour les infos/sante
Codes de statut	200 = succes, 422 = erreur de validation, 500 = erreur serveur
JSON	Format de donnees universel pour les requetes/reponses
Authentification	Cles API (simple) ou JWT (avance)
CORS	Necessaire pour les clients bases sur navigateur
Limitation du debit	Protege les ressources de calcul contre les abus
REST vs alternatives	REST pour la plupart des API IA, gRPC pour le haut debit interne

Et ensuite ?

Maintenant que vous comprenez les concepts des API REST, vous allez apprendre a les implementer en utilisant deux frameworks Python :

FastAPI — Moderne, asynchrone, auto-documente (section suivante)
Flask — Leger, flexible, largement utilise

Reference rapide du vocabulaire

Terme	Definition
Endpoint	Un chemin URL specifique qui accepte des requetes (ex. `/api/v1/predict`)
Payload	Les donnees envoyees dans le corps d'une requete ou d'une reponse
Serialisation	Conversion de structures de donnees en un format transferable (JSON)
Idempotent	Faire la meme requete plusieurs fois produit le meme resultat
Sans etat	Le serveur ne se souvient pas des requetes precedentes
Middleware	Code qui s'execute entre la reception d'une requete et le retour d'une reponse
Schema	Une description formelle de la structure de donnees attendue

Qu'est-ce qu'une API ?​

L'analogie du restaurant​

Architecture REST​

Principes REST​

Architecture d'API REST pour l'IA​

Methodes HTTP​

Endpoints API IA courants​

Codes de statut HTTP​

Familles de codes de statut​

Codes de statut essentiels pour les API IA​

Format JSON requete/reponse​

Requete de prediction​

Reponse de prediction​

Reponse d'erreur​

Bonnes pratiques de conception d'API​

1. Conventions de nommage des endpoints​

2. Validation des requetes​

3. Format de reponse coherent​

Authentification et securite​

Cles API​

JWT (JSON Web Tokens) — Apercu​

CORS (Cross-Origin Resource Sharing)​

Exemple de configuration CORS​

Limitation du debit​

Reponse de limitation du debit​

REST vs GraphQL vs gRPC​

Le cycle de vie requete/reponse​

Resume​

Et ensuite ?​