Principes de conception d'API
Maîtrisez les principes de conception d'API REST et GraphQL pour créer des API intuitives, évolutives et maintenables qui ravissent les développeurs et résistent à l'épreuve du temps.
Quand utiliser cette compétence
- Conception de nouvelles API REST ou GraphQL
- Refactorisation d'API existantes pour une meilleure utilisabilité
- Établissement de normes de conception d'API pour votre équipe
- Révision des spécifications d'API avant implémentation
- Migration entre paradigmes d'API (REST vers GraphQL, etc.)
- Création de documentation d'API conviviale pour les développeurs
- Optimisation d'API pour des cas d'utilisation spécifiques (mobile, intégrations tierces)
Concepts fondamentaux
1. Principes de conception RESTful
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 centré sur le schéma
- Les types définissent votre modèle de domaine
- Les requêtes pour lire les données
- Les mutations pour modifier les données
- Les abonnements pour les mises à jour en temps réel
Structure de requête :
- Les clients demandent exactement ce dont ils ont besoin
- Point de terminaison unique, opérations multiples
- Schéma fortement typé
- Introspection intégrée
3. Stratégies de versionnement d'API
Versionnement par URL :
/api/v1/users
/api/v2/users
Versionnement par en-tête :
Accept: application/vnd.api+json; version=1
Versionnement par paramètre de requête :
/api/users?version=1
Patrons de conception d'API REST
Patron 1 : Conception de collections de ressources
# Bon : Points de terminaison orientés ressources
GET /api/users # Lister les utilisateurs (avec pagination)
POST /api/users # Créer un utilisateur
GET /api/users/{id} # Obtenir un utilisateur spécifique
PUT /api/users/{id} # Remplacer un utilisateur
PATCH /api/users/{id} # Mettre à jour les champs d'un utilisateur
DELETE /api/users/{id} # Supprimer un utilisateur
# Ressources imbriquées
GET /api/users/{id}/orders # Obtenir les commandes d'un utilisateur
POST /api/users/{id}/orders # Créer une commande pour un utilisateur
# Mauvais : Points de terminaison orientés actions (à éviter)
POST /api/createUser
POST /api/getUserById
POST /api/deleteUser
Patron 2 : Pagination et filtrage
from typing import List, Optional
from pydantic import BaseModel, Field
class PaginationParams(BaseModel):
page: int = Field(1, ge=1, description="Numéro de page")
page_size: int = Field(20, ge=1, le=100, description="Éléments par page")
class FilterParams(BaseModel):
status: Optional[str] = None
created_after: Optional[str] = None
search: Optional[str] = None
class PaginatedResponse(BaseModel):
items: List[dict]
total: int
page: int
page_size: int
pages: int
@property
def has_next(self) -> bool:
return self.page < self.pages
@property
def has_prev(self) -> bool:
return self.page > 1
# Exemple de point de terminaison FastAPI
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
status: Optional[str] = Query(None),
search: Optional[str] = Query(None)
):
# Appliquer les filtres
query = build_query(status=status, search=search)
# Compter le total
total = await count_users(query)
# Récupérer la page
offset = (page - 1) * page_size
users = await fetch_users(query, limit=page_size, offset=offset)
return PaginatedResponse(
items=users,
total=total,
page=page,
page_size=page_size,
pages=(total + page_size - 1) // page_size
)
Patron 3 : Gestion des erreurs et codes de statut
from fastapi import HTTPException, status
from pydantic import BaseModel
class ErrorResponse(BaseModel):
error: str
message: str
details: Optional[dict] = None
timestamp: str
path: str
class ValidationErrorDetail(BaseModel):
field: str
message: str
value: Any
# Réponses d'erreur cohérentes
STATUS_CODES = {
"success": 200,
"created": 201,
"no_content": 204,
"bad_request": 400,
"unauthorized": 401,
"forbidden": 403,
"not_found": 404,
"conflict": 409,
"unprocessable": 422,
"internal_error": 500
}
def raise_not_found(resource: str, id: str):
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={
"error": "NotFound",
"message": f"{resource} introuvable",
"details": {"id": id}
}
)
def raise_validation_error(errors: List[ValidationErrorDetail]):
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail={
"error": "ValidationError",
"message": "La validation de la requête a échoué",
"details": {"errors": [e.dict() for e in errors]}
}
)
# Exemple d'utilisation
@app.get("/api/users/{user_id}")
async def get_user(user_id: str):
user = await fetch_user(user_id)
if not user:
raise_not_found("Utilisateur", user_id)
return user
Patron 4 : HATEOAS (Hypermedia comme moteur de l'état de l'application)
class UserResponse(BaseModel):
id: str
name: str
email: str
_links: dict
@classmethod
def from_user(cls, user: User, base_url: str):
return cls(
id=user.id,
name=user.name,
email=user.email,
_links={
"self": {"href": f"{base_url}/api/users/{user.id}"},
"orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
"update": {
"href": f"{base_url}/api/users/{user.id}",
"method": "PATCH"
},
"delete": {
"href": f"{base_url}/api/users/{user.id}",
"method": "DELETE"
}
}
)
Patrons de conception GraphQL
Patron 1 : Conception de schéma
# schema.graphql
# Définitions de types claires
type User {
id: ID!
email: String!
name: String!
createdAt: DateTime!
# Relations
orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
profile: UserProfile
}
type Order {
id: ID!
status: OrderStatus!
total: Money!
items: [OrderItem!]!
createdAt: DateTime!
# Référence inverse
user: User!
}
# Patron de pagination (style Relay)
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# Énumérations pour la sécurité de type
enum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
# Scalaires personnalisés
scalar DateTime
scalar Money
# Racine des requêtes
type Query {
user(id: ID!): User
users(first: Int = 20, after: String, search: String): UserConnection!
order(id: ID!): Order
}
# Racine des mutations
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(input: UpdateUserInput!): UpdateUserPayload!
deleteUser(id: ID!): DeleteUserPayload!
createOrder(input: CreateOrderInput!): CreateOrderPayload!
}
# Types d'entrée pour les mutations
input CreateUserInput {
email: String!
name: String!
password: String!
}
# Types de charge utile pour les mutations
type CreateUserPayload {
user: User
errors: [Error!]
}
type Error {
field: String
message: String!
}
Patron 2 : Conception de résolveurs
from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")
@query.field("user")
async def resolve_user(obj, info, id: str) -> Optional[dict]:
"""Résout un seul utilisateur par ID."""
return await fetch_user_by_id(id)
@query.field("users")
async def resolve_users(
obj,
info,
first: int = 20,
after: Optional[str] = None,
search: Optional[str] = None
) -> dict:
"""Résout une liste paginée d'utilisateurs."""
# Décoder le curseur
offset = decode_cursor(after) if after else 0
# Récupérer les utilisateurs
users = await fetch_users(
limit=first + 1, # En récupérer un de plus pour vérifier hasNextPage
offset=offset,
search=search
)
# Pagination
has_next = len(users) > first
if has_next:
users = users[:first]
edges = [
{
"node": user,
"cursor": encode_cursor(offset + i)
}
for i, user in enumerate(users)
]
return {
"edges": edges,
"pageInfo": {
"hasNextPage": has_next,
"hasPreviousPage": offset > 0,
"startCursor": edges[0]["cursor"] if edges else None,
"endCursor": edges[-1]["cursor"] if edges else None
},
"totalCount": await count_users(search=search)
}
@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
"""Résout les commandes d'un utilisateur (prévention N+1 avec DataLoader)."""
# Utiliser DataLoader pour regrouper les requêtes
loader = info.context["loaders"]["orders_by_user"]
orders = await loader.load(user["id"])
return paginate_orders(orders, first)
@mutation.field("createUser")
async def resolve_create_user(obj, info, input: dict) -> dict:
"""Crée un nouvel utilisateur."""
try:
# Valider l'entrée
validate_user_input(input)
# Créer l'utilisateur
user = await create_user(
email=input["email"],
name=input["name"],
password=hash_password(input["password"])
)
return {
"user": user,
"errors": []
}
except ValidationError as e:
return {
"user": None,
"errors": [{"field": e.field, "message": e.message}]
}
Patron 3 : DataLoader (prévention du problème N+1)
from aiodataloader import DataLoader
from typing import List, Optional
class UserLoader(DataLoader):
"""Charge les utilisateurs par ID en lot."""
async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
"""Charge plusieurs utilisateurs en une seule requête."""
users = await fetch_users_by_ids(user_ids)
# Mapper les résultats à l'ordre d'entrée
user_map = {user["id"]: user for user in users}
return [user_map.get(user_id) for user_id in user_ids]
class OrdersByUserLoader(DataLoader):
"""Charge les commandes par ID d'utilisateur en lot."""
async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
"""Charge les commandes pour plusieurs utilisateurs en une seule requête."""
orders = await fetch_orders_by_user_ids(user_ids)
# Grouper les commandes par user_id
orders_by_user = {}
for order in orders:
user_id = order["user_id"]
if user_id not in orders_by_user:
orders_by_user[user_id] = []
orders_by_user[user_id].append(order)
# Retourner dans l'ordre d'entrée
return [orders_by_user.get(user_id, []) for user_id in user_ids]
# Configuration du contexte
def create_context():
return {
"loaders": {
"user": UserLoader(),
"orders_by_user": OrdersByUserLoader()
}
}
Bonnes pratiques
API REST
- Nommage cohérent : Utilisez des noms au pluriel pour les collections (
/users, pas/user) - Sans état : Chaque requête contient toutes les informations nécessaires
- Utilisez les codes de statut HTTP correctement : 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
- Schéma d'abord : Concevez le schéma avant d'écrire les résolveurs
- Évitez le N+1 : Utilisez DataLoaders pour une récupération efficace des données
- Validation des entrées : Validez au niveau du schéma et des résolveurs
- Gestion des erreurs : Retournez des erreurs structurées dans les charges utiles des mutations
- Pagination : Utilisez la pagination basée sur les curseurs (spécification Relay)
- Obsolescence : Utilisez la directive
@deprecatedpour une migration progressive - Surveillance : Suivez la complexité des requêtes et le temps d'exécution
Pièges courants
- Sur-récupération / Sous-récupération (REST) : Résolu dans GraphQL mais nécessite DataLoaders
- Changements cassants : Versionnez les API ou utilisez des stratégies d'obsolescence
- Formats d'erreur incohérents : Standardisez les réponses d'erreur
- Absence de limites de débit : Les API sans limites sont vulnérables aux abus
- Documentation de qualité médiocre : 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 : Patrons et anti-patrons de schémas GraphQL
- references/api-versioning-strategies.md : Approches de versionnement et chemins de migration
- assets/rest-api-template.py : Modèle d'API REST FastAPI
- assets/graphql-schema-template.graphql : Exemple de schéma GraphQL complet
- assets/api-design-checklist.md : Liste de vérification de révision avant implémentation
- scripts/openapi-generator.py : Générer des spécifications OpenAPI à partir du code