Que fait Principes de Conception d'API ?
Maîtrisez les principes de conception d'API REST et GraphQL pour construire des API intuitives, évolutives et maintenables qui raviront les développeurs et résisteront à l'épreuve du temps.
Quand utiliser cette compétence
- Concevoir de nouvelles API REST ou GraphQL
- Refactorer des API existantes pour une meilleure utilisabilité
- Établir des normes de conception d'API pour votre équipe
- Examiner les spécifications d'API avant leur implémentation
- Migrer entre les paradigmes d'API (REST vers GraphQL, etc.)
- Créer une documentation d'API adaptée aux développeurs
- Optimiser les API pour des cas d'utilisation spécifiques (mobile, intégrations tierces)
Concepts Fondamentaux
1. Principes de Conception REST
Architecture Orientée Ressource
- Les ressources sont des noms (utilisateurs, commandes, produits), pas des verbes
- Utilisez les méthodes HTTP pour les actions (GET, POST, PUT, PATCH, DELETE)
- Les URL représentent des hiérarchies de ressources
- Conventions de nommage cohérentes
Sémantique des Méthodes HTTP :
GET: Récupérer des ressources (idempotent, sûr)POST: Créer de nouvelles ressourcesPUT: Remplacer entièrement une ressource (idempotent)PATCH: Mises à jour partielles de ressourcesDELETE: Supprimer des ressources (idempotent)
2. Principes de Conception GraphQL
Développement Schema-First
- Les types définissent votre modèle de domaine
- Les requêtes (Queries) pour lire les données
- Les mutations pour modifier les données
- Les abonnements (Subscriptions) pour les mises à jour en temps réel
Structure de Requête :
- Les clients demandent exactement ce dont ils ont besoin
- Un seul point de terminaison, plusieurs opérations
- Schéma fortement typé
- Introspection intégrée
3. Stratégies de Versioning d'API
Versioning par URL :
/api/v1/utilisateurs
/api/v2/utilisateurs
Versioning par En-tête :
Accept: application/vnd.api+json; version=1
Versioning par Paramètre de Requête :
/api/utilisateurs?version=1
Modèles de Conception REST
Modèle 1 : Conception de Collection de Ressources
# Bon : Points de terminaison orientés ressources
GET /api/utilisateurs # Lister les utilisateurs (avec pagination)
POST /api/utilisateurs # Créer un utilisateur
GET /api/utilisateurs/{id} # Obtenir un utilisateur spécifique
PUT /api/utilisateurs/{id} # Remplacer un utilisateur
PATCH /api/utilisateurs/{id} # Mettre à jour les champs d'un utilisateur
DELETE /api/utilisateurs/{id} # Supprimer un utilisateur
# Ressources imbriquées
GET /api/utilisateurs/{id}/commandes # Obtenir les commandes d'un utilisateur
POST /api/utilisateurs/{id}/commandes # Créer une commande pour un utilisateur
# Mauvais : Points de terminaison orientés actions (à éviter)
POST /api/creerUtilisateur
POST /api/obtenirUtilisateurParId
POST /api/supprimerUtilisateur
Modèle 2 : Pagination et Filtrage
from typing import List, Optional
from pydantic import BaseModel, Field
class ParametresPagination(BaseModel):
page: int = Field(1, ge=1, description="Numéro de page")
taille_page: int = Field(20, ge=1, le=100, description="Éléments par page")
class ParametresFiltre(BaseModel):
statut: Optional[str] = None
cree_apres: Optional[str] = None
recherche: Optional[str] = None
class ReponsePaginee(BaseModel):
elements: List[dict]
total: int
page: int
taille_page: int
pages: int
@property
def a_suivant(self) -> bool:
return self.page < self.pages
@property
def a_precedent(self) -> bool:
return self.page > 1
# Exemple de point de terminaison FastAPI
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/api/utilisateurs", response_model=ReponsePaginee)
async def lister_utilisateurs(
page: int = Query(1, ge=1),
taille_page: int = Query(20, ge=1, le=100),
statut: Optional[str] = Query(None),
recherche: Optional[str] = Query(None)
):
# Appliquer les filtres
requete = construire_requete(statut=statut, recherche=recherche)
# Compter le total
total = await compter_utilisateurs(requete)
# Récupérer la page
offset = (page - 1) * taille_page
utilisateurs = await recuperer_utilisateurs(requete, limite=taille_page, offset=offset)
return ReponsePaginee(
elements=utilisateurs,
total=total,
page=page,
taille_page=taille_page,
pages=(total + taille_page - 1) // taille_page
)
Modèle 3 : Gestion des Erreurs et Codes de Statut
from fastapi import HTTPException, status
from pydantic import BaseModel
class ReponseErreur(BaseModel):
erreur: str
message: str
details: Optional[dict] = None
horodatage: str
chemin: str
class DetailErreurValidation(BaseModel):
champ: str
message: str
valeur: Any
# Réponses d'erreur cohérentes
CODES_STATUT = {
"succes": 200,
"cree": 201,
"aucun_contenu": 204,
"mauvaise_requete": 400,
"non_autorise": 401,
"interdit": 403,
"non_trouve": 404,
"conflit": 409,
"non_traitable": 422,
"erreur_interne": 500
}
def lever_non_trouve(ressource: str, id: str):
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={
"error": "NonTrouve",
"message": f"{ressource} introuvable",
"details": {"id": id}
}
)
def lever_erreur_validation(erreurs: List[DetailErreurValidation]):
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail={
"error": "ErreurValidation",
"message": "La validation de la requête a échoué",
"details": {"errors": [e.dict() for e in erreurs]}
}
)
# Exemple d'utilisation
@app.get("/api/utilisateurs/{utilisateur_id}")
async def obtenir_utilisateur(utilisateur_id: str):
utilisateur = await recuperer_utilisateur(utilisateur_id)
if not utilisateur:
lever_non_trouve("Utilisateur", utilisateur_id)
return utilisateur
Modèle 4 : HATEOAS (Hypermedia as the Engine of Application State)
class ReponseUtilisateur(BaseModel):
id: str
nom: str
email: str
_liens: dict
@classmethod
def depuis_utilisateur(cls, utilisateur: User, url_base: str):
return cls(
id=utilisateur.id,
nom=utilisateur.nom,
email=utilisateur.email,
_liens={
"self": {"href": f"{url_base}/api/utilisateurs/{utilisateur.id}"},
"commandes": {"href": f"{url_base}/api/utilisateurs/{utilisateur.id}/commandes"},
"mettre_a_jour": {
"href": f"{url_base}/api/utilisateurs/{utilisateur.id}",
"method": "PATCH"
},
"supprimer": {
"href": f"{url_base}/api/utilisateurs/{utilisateur.id}",
"method": "DELETE"
}
}
)
Modèles de Conception GraphQL
Modèle 1 : Conception de Schéma
# schema.graphql
# Définitions de types claires
type Utilisateur {
id: ID!
email: String!
nom: String!
creeLe: DateTime!
# Relations
commandes(premier: Int = 20, apres: String, statut: StatutCommande): ConnexionCommande!
profil: ProfilUtilisateur
}
type Commande {
id: ID!
statut: StatutCommande!
total: Monnaie!
articles: [ArticleCommande!]!
creeLe: DateTime!
# Référence arrière
utilisateur: Utilisateur!
}
# Modèle de pagination (style Relay)
type ConnexionCommande {
aretes: [AreteCommande!]!
infosPage: InfosPage!
totalCount: Int!
}
type AreteCommande {
noeud: Commande!
curseur: String!
}
type InfosPage {
aPageSuivante: Boolean!
aPagePrecedente: Boolean!
curseurDebut: String
curseurFin: String
}
# Énumérations pour la sécurité des types
enum StatutCommande {
EN_ATTENTE
CONFIRMEE
EXPEDIEE
LIVREE
ANNULEE
}
# Scalaires personnalisés
scalar DateTime
scalar Monnaie
# Racine de requête
type Query {
utilisateur(id: ID!): Utilisateur
utilisateurs(premier: Int = 20, apres: String, recherche: String): ConnexionUtilisateur!
commande(id: ID!): Commande
}
# Racine de mutation
type Mutation {
creerUtilisateur(entree: EntreeCreerUtilisateur!): PayloadCreerUtilisateur!
mettreAJourUtilisateur(entree: EntreeMettreAJourUtilisateur!): PayloadMettreAJourUtilisateur!
supprimerUtilisateur(id: ID!): PayloadSupprimerUtilisateur!
creerCommande(entree: EntreeCreerCommande!): PayloadCreerCommande!
}
# Types d'entrée pour les mutations
input EntreeCreerUtilisateur {
email: String!
nom: String!
motDePasse: String!
}
# Types de payload pour les mutations
type PayloadCreerUtilisateur {
utilisateur: Utilisateur
erreurs: [Erreur!]
}
type Erreur {
champ: String
message: String!
}
Modèle 2 : Conception de Résolveur
from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
requete = QueryType()
mutation = MutationType()
type_utilisateur = ObjectType("Utilisateur")
@requete.field("utilisateur")
async def resoudre_utilisateur(obj, info, id: str) -> Optional[dict]:
"""Résout un seul utilisateur par ID."""
return await recuperer_utilisateur_par_id(id)
@requete.field("utilisateurs")
async def resoudre_utilisateurs(
obj,
info,
premier: int = 20,
apres: Optional[str] = None,
recherche: Optional[str] = None
) -> dict:
"""Résout une liste paginée d'utilisateurs."""
# Décoder le curseur
decalage = decoder_curseur(apres) if apres else 0
# Récupérer les utilisateurs
utilisateurs = await recuperer_utilisateurs(
limite=premier + 1, # En récupérer un de plus pour vérifier aPageSuivante
decalage=decalage,
recherche=recherche
)
# Pagination
a_suivant = len(utilisateurs) > premier
if a_suivant:
utilisateurs = utilisateurs[:premier]
aretes = [
{
"noeud": utilisateur,
"curseur": encoder_curseur(decalage + i)
}
for i, utilisateur in enumerate(utilisateurs)
]
return {
"edges": aretes,
"pageInfo": {
"hasNextPage": a_suivant,
"hasPreviousPage": decalage > 0,
"startCursor": aretes[0]["curseur"] if aretes else None,
"endCursor": aretes[-1]["curseur"] if aretes else None
},
"totalCount": await compter_utilisateurs(recherche=recherche)
}
@type_utilisateur.field("commandes")
async def resoudre_commandes_utilisateur(utilisateur: dict, info, premier: int = 20) -> dict:
"""Résout les commandes d'un utilisateur (prévention N+1 avec DataLoader)."""
# Utiliser DataLoader pour regrouper les requêtes
chargeur = info.context["chargeurs"]["commandes_par_utilisateur"]
commandes = await chargeur.load(utilisateur["id"])
return paginer_commandes(commandes, premier)
@mutation.field("creerUtilisateur")
async def resoudre_creer_utilisateur(obj, info, entree: dict) -> dict:
"""Crée un nouvel utilisateur."""
try:
# Valider l'entrée
valider_entree_utilisateur(entree)
# Créer l'utilisateur
utilisateur = await creer_utilisateur(
email=entree["email"],
nom=entree["nom"],
motDePasse=hacher_mot_de_passe(entree["motDePasse"])
)
return {
"utilisateur": utilisateur,
"erreurs": []
}
except ErreurValidation as e:
return {
"utilisateur": None,
"erreurs": [{"champ": e.champ, "message": e.message}]
}
Modèle 3 : DataLoader (Prévention du Problème N+1)
from aiodataloader import DataLoader
from typing import List, Optional
class ChargeurUtilisateur(DataLoader):
"""Charge les utilisateurs par lots par ID."""
async def batch_load_fn(self, ids_utilisateurs: List[str]) -> List[Optional[dict]]:
"""Charge plusieurs utilisateurs en une seule requête."""
utilisateurs = await recuperer_utilisateurs_par_ids(ids_utilisateurs)
# Mapper les résultats à l'ordre d'entrée
map_utilisateurs = {utilisateur["id"]: utilisateur for utilisateur in utilisateurs}
return [map_utilisateurs.get(id_utilisateur) for id_utilisateur in ids_utilisateurs]
class ChargeurCommandesParUtilisateur(DataLoader):
"""Charge les commandes par lots par ID d'utilisateur."""
async def batch_load_fn(self, ids_utilisateurs: List[str]) -> List[List[dict]]:
"""Charge les commandes pour plusieurs utilisateurs en une seule requête."""
commandes = await recuperer_commandes_par_ids_utilisateurs(ids_utilisateurs)
# Grouper les commandes par utilisateur_id
commandes_par_utilisateur = {}
for commande in commandes:
id_utilisateur = commande["utilisateur_id"]
if id_utilisateur not in commandes_par_utilisateur:
commandes_par_utilisateur[id_utilisateur] = []
commandes_par_utilisateur[id_utilisateur].append(commande)
# Retourner dans l'ordre d'entrée
return [commandes_par_utilisateur.get(id_utilisateur, []) for id_utilisateur in ids_utilisateurs]
# Configuration du contexte
def creer_contexte():
return {
"chargeurs": {
"utilisateur": ChargeurUtilisateur(),
"commandes_par_utilisateur": ChargeurCommandesParUtilisateur()
}
}
Bonnes Pratiques
API REST
- Nommage Cohérent : Utilisez des noms au pluriel pour les collections (
/utilisateurs, pas/utilisateur) - Sans État : Chaque requête contient toutes les informations nécessaires
- Utilisez Correctement les Codes de Statut HTTP : 2xx succès, 4xx erreurs client, 5xx erreurs serveur
- Versionnez Votre API : Planifiez les changements cassants dès le premier jour
- Pagination : Paginez toujours les grandes collections
- Limitation de Débit : Protégez votre API avec des limites de débit
- Documentation : Utilisez OpenAPI/Swagger pour une documentation interactive
API GraphQL
- Schema d'Abord : Concevez le schéma avant d'écrire les résolveurs
- Évitez N+1 : Utilisez DataLoaders pour une récupération de données efficace
- Validation des Entrées : Validez au niveau du schéma et des résolveurs
- Gestion des Erreurs : Retournez des erreurs structurées dans les payloads de mutation
- Pagination : Utilisez la pagination basée sur les curseurs (spécification Relay)
- Dépréciation : Utilisez la directive
@deprecatedpour une migration progressive - Surveillance : Suivez la complexité des requêtes et le temps d'exécution
Pièges Courants
- Surcharge/Sous-charge (REST) : Résolu dans GraphQL mais nécessite des DataLoaders
- Changements Cassants : Versionnez les API ou utilisez des stratégies de dépréciation
- Formats d'Erreur Incohérents : Standardisez les réponses d'erreur
- Limites de Débit Manquantes : Les API sans limites sont vulnérables aux abus
- Mauvaise Documentation : Les API non documentées frustrent les développeurs
- Ignorer la Sémantique HTTP : POST pour des opérations idempotentes brise les attentes
- Couplage Fort : La structure de l'API ne doit pas refléter le schéma de la base de données
Ressources
- references/rest-best-practices.md : Guide complet de conception d'API REST
- references/graphql-schema-design.md : Modèles et anti-modèles de schéma GraphQL
- references/api-versioning-strategies.md : Approches de versionnage et chemins de migration
- assets/rest-api-template.py : Modèle d'API REST FastAPI
- assets/graphql-schema-template.graphql : Exemple complet de schéma GraphQL
- assets/api-design-checklist.md : Liste de contrôle de pré-implémentation
- scripts/openapi-generator.py : Générer des spécifications OpenAPI à partir du code