Conception d'API

Que fait Conception d'API ?

Choisir le bon type d'API

Type	Idéal pour	Éviter quand
REST	API publiques, CRUD, clients simples, IoT	Données imbriquées complexes, itération rapide du schéma
GraphQL	Applications mobiles, données imbriquées complexes, clients multiples	CRUD simples, petites équipes novices
tRPC	Monorepos TypeScript, API internes full-stack TS	Clients non-TypeScript, API publiques
gRPC	Communications microservices haute performance, streaming	Clients navigateurs, cas d'usage simples

---

Conception d'API REST

Conventions d'URL

GET    /users              ← liste
GET    /users/{id}         ← élément unique
POST   /users              ← création
PUT    /users/{id}         ← remplacement
PATCH  /users/{id}         ← mise à jour partielle
DELETE /users/{id}         ← suppression

# Ressources imbriquées
GET    /users/{id}/orders
POST   /users/{id}/orders

# Actions (quand les verbes REST ne suffisent pas)
POST   /orders/{id}/cancel
POST   /users/{id}/activate

Codes de statut HTTP

Code	Utilisation
200	GET, PUT, PATCH réussis
201	POST réussi avec création
204	DELETE réussi (sans corps)
400	Échec de validation, mauvaise requête
401	Authentification manquante/invalide
403	Authentifié mais non autorisé
404	Ressource non trouvée
409	Conflit (doublon, incohérence de version)
422	Entité non traitable (erreurs sémantiques)
429	Limite de débit dépassée
500	Erreur serveur inattendue

Enveloppe de réponse

// Collection
{
  "data": [...],
  "meta": { "total": 100, "page": 1, "perPage": 20 }
}

// Ressource unique
{ "data": { "id": "1", "name": "James" } }

// Erreur
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La validation a échoué",
    "details": [{ "field": "email", "issue": "Format invalide" }]
  }
}

---

Principes de conception d'API

Stratégie de versionnage

# Versionnage dans l'URL (le plus visible, le plus simple à router)
/v1/utilisateurs
/v2/utilisateurs

# Versionnage par en-tête (URL plus propres)
Accept: application/vnd.api+json;version=2

Ne jamais casser les clients existants. Déprécier, puis supprimer.

Pagination

# Décalage (simple, adapté aux petits ensembles de données)
GET /articles?page=2&perPage=20

# Curseur (rapide pour les grands ensembles, idéal pour le défilement infini)
GET /articles?cursor=eyJpZCI6MTAwfQ&limit=20

Filtrage et tri

GET /commandes?status=en_attente&userId=123
GET /produits?sort=-prix,nom    # préfixe - = ordre décroissant
GET /produits?fields=id,nom,prix  # jeux de champs restreints

Idempotence

# Inclure une clé d'idempotence pour les opérations non idempotentes
POST /paiements
Idempotency-Key: uuid-unique-genere-par-client

---

Conception GraphQL

Règles de conception du schéma

• Décrire le domaine métier, pas la structure de la base de données
• Utiliser le modèle de connexions pour les listes (prêt pour la pagination)
• Les mutations renvoient l'objet modifié
• Utiliser des énumérations pour les ensembles de valeurs finis
• Ajouter des descriptions à tous les types et champs

type Query {
  utilisateur(id: ID!): Utilisateur
  utilisateurs(filtre: FiltreUtilisateur, pagination: PaginationInput): ConnexionUtilisateur!
}

type Mutation {
  creerUtilisateur(entree: EntreeCreerUtilisateur!): PayloadCreerUtilisateur!
  mettreAJourUtilisateur(id: ID!, entree: EntreeMettreAJourUtilisateur!): PayloadMettreAJourUtilisateur!
}

type ConnexionUtilisateur {
  aretes: [AreteUtilisateur!]!
  pageInfo: InfoPage!
  nombreTotal: Int!
}

---

Liste de vérification de sécurité d'API

• Tous les endpoints nécessitent une authentification (sauf explicite publique)
• Autorisation vérifiée par ressource, pas seulement par route
• Limitation de débit sur tous les endpoints, plus stricte sur les endpoints d'authentification
• Validation des entrées sur chaque paramètre et champ du corps
• Les données sensibles ne sont pas renvoyées sauf nécessité explicite
• CORS configuré avec une liste blanche explicite
• Stratégie de versionnage d'API définie avant de devenir publique