5 min de lecture

REST API design - 00 - Pourquoi le design de ton API change tout

Une API mal désignée ruine l'experience développeur. Introduction a cette serie de 24 articles sur le design REST.

REST API design introduction
REST API design 1 / 25
  1. 01 REST API design - 00 - Pourquoi le design de ton API change tout
  2. 02 REST API design - 01 - Les principes REST que personne ne lit
  3. 03 REST API design - 02 - Des URLs qui ont du sens
  4. 04 REST API design - 03 - Les méthodes HTTP, pour de vrai
  5. 05 REST API design - 04 - Les codes de statut HTTP qu'il faut connaître
  6. 06 REST API design - 05 - Body, headers et le diable dans les détails
  7. 07 REST API design - 06 - La pagination, ou comment ne pas tuer ta base
  8. 08 REST API design - 07 - Filtrage et tri sans prise de tête
  9. 09 REST API design - 08 - La validation avec Zod, gardien de ton API
  10. 10 REST API design - 09 - Erreurs : un format que tes clients vont adorer
  11. 11 REST API design - 10 - Authentification : JWT, API keys et OAuth2
  12. 12 REST API design - 11 - Versioning : quand et comment faire évoluer ton API
  13. 13 REST API design - 12 - CORS : comprendre et debugger les erreurs cross-origin
  14. 14 REST API design - 13 - Rate limiting : protéger ton API sans frustrer tes clients
  15. 15 REST API design - 14 - Caching : les bonnes réponses sont celles qu'on n'envoie pas
  16. 16 REST API design - 15 - Upload de fichiers : multipart, signed URLs et streaming
  17. 17 REST API design - 16 - Relations entre ressources : embarquer, lier ou les deux
  18. 18 REST API design - 17 - HATEOAS : des liens dans tes réponses
  19. 19 REST API design - 18 - OpenAPI : le contrat entre ton API et le monde
  20. 20 REST API design - 19 - Documentation : une API non documentee est une API inutile
  21. 21 REST API design - 20 - Testing : tester ton API sans devenir fou
  22. 22 REST API design - 21 - Webhooks : quand c'est ton API qui appelle
  23. 23 REST API design - 22 - Performance : quand chaque milliseconde compte
  24. 24 REST API design - 23 - Sécurité : les attaques que tu vas subir (et comment t'en protéger)
  25. 25 REST API design - 24 - Glossaire : tous les termes REST API en un seul endroit
Suivant →

00 - Pourquoi le design de ton API change tout

Ce que tu vas apprendre

  • Pourquoi une API mal désignée est un cauchemar pour les consommateurs
  • Ce que "bon design" veut dire dans le contexte REST
  • Ce que cette serie de 24 articles couvre

Prerequisites

Aucun. Si tu sais ce qu'est une requête HTTP, tu es pret.

L'API qui m'a fait perdre un week-end

Il y a quelques annees, j'ai du intégrer une API de gestion de livraisons pour un projet e-commerce. La doc etait un PDF de 47 pages. Pas de Swagger, pas d'OpenAPI. Un PDF.

Pour créer une commande, il fallait faire un POST sur /api/v2/doAction avec un body qui contenait un champ actionType: "CREATE_ORDER". Pour la mettre à jour ? Meme endpoint, actionType: "UPDATE_ORDER". Pour la supprimer ? Tu devines. Meme endpoint, actionType: "DELETE_ORDER". Les erreurs revenaient toutes en 200 avec un champ success: false et un message générique du style "An error occurred".

J'ai passe un samedi et un dimanche a deviner comment cette API fonctionnait. Un week-end perdu parce que quelqu'un a décidé que les verbes HTTP et les codes de statut, c'etait optionnel.

Le design d'API, c'est du design d'interface

Quand on parle de "design", on pense souvent UI. Des boutons, des couleurs, des animations. Mais une API, c'est aussi une interface. Sauf que tes utilisateurs sont des développeurs, et leur experience s'appelle la DX -- Developer Experience.

Une bonne DX, ca veut dire :

  • Tu devines comment l'API fonctionne avant de lire la doc
  • Les erreurs te disent quoi corriger
  • Les conventions sont coherentes d'un endpoint a l'autre
  • Tu n'as pas besoin d'appeler le dev qui l'a écrite pour comprendre un cas limite

Une mauvaise DX, ca veut dire des tickets de support, des bugs d'intégration, des développeurs frustrés qui finissent par contourner ton API avec des hacks. Et a terme, personne ne veut utiliser ton service.

Ce que REST n'est pas

REST n'est pas "faire du CRUD avec Express". C'est un style architectural avec des contraintes precises, formalisees par Roy Fielding dans sa these de 2000. On va les voir en détail dans l'article suivant.

REST n'est pas non plus la seule option. GraphQL, gRPC, tRPC -- chaque approche a ses forces. Mais REST reste le standard dominant pour les API publiques, et c'est celui que tu rencontreras le plus souvent. Bien le maîtriser, c'est un investissement qui paie sur chaque projet.

Ce que cette serie couvre

Voici le plan complet des 24 articles :

# Sujet
00 Introduction -- pourquoi le design compte
01 Principes REST et modèle de maturite
02 Design des URLs
03 Méthodes HTTP
04 Codes de statut
05 Body, headers et content negotiation
06 Pagination
07 Filtrage et tri
08 Validation des entrees
09 Gestion des erreurs
10 Authentification et autorisation
11 Versioning
12 HATEOAS et hypermedia
13 Rate limiting et throttling
14 Caching HTTP
15 Documentation avec OpenAPI
16 Tests d'API
17 Upload de fichiers
18 Webhooks
19 Batch opérations
20 API temps réel (SSE, WebSocket)
21 Sécurité OWASP pour API
22 Performance et optimisation
23 Migration et deprecation

Chaque article est independant, mais ils se construisent les uns sur les autres. Je te recommande de les lire dans l'ordre si tu debutes, ou de piocher ce qui t'interesse si tu as deja de l'experience.

Mon approche

Je ne vais pas te reciter la spec HTTP. Je vais te montrer des cas concrets, du code TypeScript, des erreurs que j'ai faites et que j'ai vues en code review. Chaque article contient des exemples que tu peux copier et adapter.

Mon avis est que le meilleur design d'API, c'est celui qui ne surprend pas. Quand un développeur utilise ton API et que tout fonctionne comme il s'y attend, sans lire la doc, tu as gagne. C'est le principe de moindre surprise, et c'est le fil rouge de toute cette serie.

typescript// Ce que tu vas apprendre a construire
// Une API previsible, coherente, bien documentee

// GET /api/users/42/orders?status=shipped&sort=-createdAt&page=2&limit=20
// -> 200 OK
{
  "data": [
    {
      "id": "order_891",
      "status": "shipped",
      "total": 49.99,
      "createdAt": "2026-03-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 87,
    "totalPages": 5
  }
}

Ca a l'air simple. Et ca devrait l'etre. Mais arriver a ce niveau de clarte demande de prendre des dizaines de micro-décisions. Cette serie est la pour t'aider a les prendre.

Tu peux retrouver mes autres series d'articles sur paltemps.fr.

Résumé

  • Le design d'API est du design d'interface pour développeurs
  • Une mauvaise API généré du support, des bugs, et de la frustration
  • REST est un style architectural avec des regles precises, pas juste du CRUD
  • Cette serie couvre 24 aspects du design REST, du basique a l'avance

Suivant : Principes REST et modèle de maturite

Sources

Publie le · Mis a jour le

Articles liés

Réservez un audit gratuit de 30 minutes. Je vous montre concrètement ce qu'on peut automatiser.

Découvrir Pal'Temps