Développement API : les bonnes pratiques

Bien développer une API, c’est d’abord la concevoir comme un produit : un contrat clair (documenté avec OpenAPI), des URL construites autour de ressources et de méthodes HTTP, des codes d’erreur standard, une sécurité pensée dès le départ (authentification, contrôle d’accès objet par objet, limitation du débit) et un versionnement qui évite de casser les applications déjà branchées. Le reste (pagination, cache, supervision) vient consolider ces fondations.

Cet article s’adresse à ceux qui font développer ou développent une API REST. Pour la définition et les usages en entreprise, lisez d’abord qu’est-ce qu’une API. Ici, on passe en revue les bonnes pratiques, avec des exemples et les normes à jour.

• Qu’est-ce qu’une API, en deux minutes ?
• Pourquoi commencer par le contrat et la documentation ?
• Comment nommer les routes et utiliser les méthodes HTTP ?
• Quel format de données utiliser ?
• Comment gérer les erreurs ?
• Comment sécuriser une API ?
• Pourquoi limiter le débit ?
• Comment filtrer, trier et paginer ?
• Comment garder une API rapide ?
• Comment faire évoluer une API sans tout casser ?
• Quelles erreurs éviter ?
• Questions fréquentes
• Sources

Qu’est-ce qu’une API, en deux minutes ?

API signifie Application Programming Interface, interface de programmation d’application. C’est un point d’entrée qui permet à un logiciel de demander des données ou des actions à un autre, selon des règles fixées à l’avance.

L’image classique est celle du restaurant : vous (l’application cliente) consultez le menu (la documentation), le serveur (l’API) transmet votre commande à la cuisine (le système) et vous rapporte le plat (la réponse). Vous n’avez pas besoin de savoir comment fonctionne la cuisine. Un comparateur de vols fonctionne ainsi : il interroge les API de plusieurs compagnies aériennes et affiche leurs réponses sur une seule page.

La plupart des API web suivent le style REST, décrit par Roy Fielding dans sa thèse de 2000 : un client et un serveur séparés, des requêtes sans état (chaque requête contient tout ce qu’il faut pour être traitée), des réponses qui indiquent si elles peuvent être mises en cache, et une interface uniforme fondée sur des ressources.

Pourquoi commencer par le contrat et la documentation ?

Une API est utilisée par des gens qui n’ont pas écrit son code. La documentation n’est donc pas un bonus : c’est le produit. La bonne pratique actuelle consiste à écrire d’abord le contrat (routes, paramètres, formats de requête et de réponse, erreurs possibles) au format OpenAPI, le standard de description des API HTTP. Sa version la plus récente est la 3.2.1, publiée le 10 septembre 2026.

Ce fichier sert à tout : générer une documentation consultable et testable, produire des exemples de code, valider automatiquement les requêtes, et discuter du besoin avec le client avant d’écrire une ligne de code. Une bonne documentation contient pour chaque route : la méthode, les paramètres, un exemple de requête, un exemple de réponse, les codes d’erreur et les limites d’usage.

Comment nommer les routes et utiliser les méthodes HTTP ?

Trois règles simples rendent une API lisible :

1. Des noms, pas des verbes dans les URL : /articles plutôt que /getArticles. L’action est portée par la méthode HTTP.
2. Des collections au pluriel : /articles pour la liste, /articles/42 pour un élément.
3. Une imbrication limitée pour les ressources liées : /articles/42/commentaires, sans aller au-delà de deux niveaux.

Méthode	Exemple	Effet
GET	GET /articles	Lire la liste (sans rien modifier)
POST	POST /articles	Créer un article
PUT	PUT /articles/42	Remplacer entièrement l’article 42
PATCH	PATCH /articles/42	Modifier une partie de l’article 42
DELETE	DELETE /articles/42	Supprimer l’article 42

GET, PUT et DELETE sont définies dans la RFC 9110 (sémantique HTTP, 2022), PATCH dans la RFC 5789. Respectez leur sens : un GET ne doit jamais modifier de données, sinon un robot ou un cache peut déclencher des actions par accident.

Et l’en-tête X-HTTP-Method-Override ? L’ancienne version de cet article le recommandait. Cet en-tête non standard permettait d’envoyer un PUT ou un DELETE déguisé en POST, pour des clients ou des proxys qui ne géraient que GET et POST. Les clients HTTP actuels savent envoyer toutes les méthodes : ne l’ajoutez que si un client ancien l’exige vraiment.

Quel format de données utiliser ?

JSON (RFC 8259) est le format par défaut des API web : léger, lisible et lu nativement par JavaScript. Renvoyez l’en-tête Content-Type: application/json, gardez un style de nommage constant (par exemple date_creation partout, jamais un mélange avec dateCreation) et des dates au format ISO 8601 (2026-09-26T10:00:00Z). XML reste pertinent quand un standard l’impose : notre comparatif JSON vs XML détaille les cas.

Comment gérer les erreurs ?

Utilisez les codes de statut HTTP pour ce qu’ils signifient, et un corps d’erreur au format standard Problem Details (RFC 9457, 2023, qui remplace la RFC 7807), avec le type de média application/problem+json.

Code	Signification	Quand l’utiliser
400	Bad Request	Requête mal formée
401	Unauthorized	Pas authentifié, ou jeton invalide
403	Forbidden	Authentifié mais pas autorisé
404	Not Found	Ressource introuvable
409	Conflict	Conflit avec l’état actuel (doublon, version dépassée)
422	Unprocessable Content	Format correct mais données invalides
429	Too Many Requests	Limite de débit atteinte (RFC 6585)
500	Internal Server Error	Erreur inattendue côté serveur
502 / 503	Bad Gateway / Service Unavailable	Service amont en erreur, ou maintenance

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.exemple.fr/erreurs/email-invalide",
  "title": "Adresse e-mail invalide",
  "status": 422,
  "detail": "Le champ email doit contenir une adresse valide.",
  "instance": "/clients"
}

Ne renvoyez jamais de trace technique (pile d’appels, requête SQL) au client : elle aide surtout les attaquants.

Comment sécuriser une API ?

La référence est le Top 10 OWASP de la sécurité des API (édition 2023). Ses trois premières failles concernent l’autorisation et l’authentification :

• API1, contrôle d’accès au niveau objet défaillant : l’utilisateur A peut lire la facture de B simplement en changeant /factures/41 en /factures/42. Vérifiez les droits sur chaque objet, à chaque requête.
• API2, authentification défaillante : jetons mal protégés, mots de passe sans limite d’essais.
• API3, contrôle d’accès au niveau des propriétés : l’API renvoie trop de champs, ou accepte qu’un client modifie un champ qu’il ne devrait pas (par exemple role).

Les mesures de base :

• HTTPS partout, sans exception.
• Une authentification adaptée : clé d’API pour un échange serveur à serveur simple, OAuth 2.0 (RFC 6749) quand une application tierce agit pour le compte d’un utilisateur.
• Des rôles et des droits minimaux (lecture seule par défaut).
• La validation de toutes les entrées, y compris les données reçues d’autres API : l’OWASP classe en 10e position le fait de faire trop confiance aux API tierces.
• Un inventaire des versions et routes exposées (API9) : une vieille version oubliée reste une porte ouverte.
• Des règles CORS restrictives si l’API est appelée depuis un navigateur.

La sécurité doit rester utilisable : un parcours d’authentification trop lourd pousse les intégrateurs à des contournements. Pour aller plus loin, lisez comment améliorer la sécurité des applications web.

Pourquoi limiter le débit ?

Chaque requête consomme du processeur, de la mémoire et de la bande passante. Sans limite, un client mal codé ou malveillant peut saturer le service : c’est la faille API4 de l’OWASP (consommation de ressources non restreinte). La limitation du débit (rate limiting) fixe un nombre maximal de requêtes par client et par période, et répond 429 Too Many Requests au-delà, idéalement avec un en-tête Retry-After qui indique quand réessayer.

On peut prévoir plusieurs paliers selon les clients (gratuit, partenaire, interne) et protéger plus fort les actions sensibles comme la connexion ou l’envoi de SMS (API6, accès non restreint aux flux métier sensibles).

Comment filtrer, trier et paginer ?

Une route qui renvoie toute une table finit toujours par devenir lente. Prévoyez dès le départ :

• Le filtrage par paramètres : GET /commandes?statut=payee&client=12
• Le tri : GET /commandes?tri=-date (le signe moins pour l’ordre décroissant, à documenter)
• La pagination : ?page=2&par_page=50, ou par curseur (?apres=abc123) pour les gros volumes, plus stable quand des données sont ajoutées en cours de lecture
• Une taille maximale imposée côté serveur, quel que soit le paramètre envoyé

Comment garder une API rapide ?

• Cache HTTP : en-têtes Cache-Control et ETag pour les données qui changent peu. Le client peut alors demander « a-t-elle changé ? » et recevoir un 304 Not Modified sans corps.
• Cache applicatif : une base en mémoire (Redis par exemple) pour les calculs coûteux souvent redemandés.
• Traitements asynchrones : pour une tâche longue (génération de PDF, import), répondre 202 Accepted et traiter en arrière-plan, puis prévenir le client par un webhook.
• Supervision : journaux structurés, temps de réponse et taux d’erreur par route, alertes.

Comment faire évoluer une API sans tout casser ?

Une fois publiée, une API est utilisée par des applications que vous ne contrôlez pas. Ajouter un champ ou une route ne casse rien. Renommer, supprimer ou changer le type d’un champ casse les clients existants : c’est un changement majeur, qui justifie une nouvelle version (/v2/ dans l’URL ou un en-tête dédié). Annoncez les dépréciations à l’avance, maintenez l’ancienne version pendant une période définie, puis retirez-la vraiment.

Quelles erreurs éviter ?

• Répondre 200 OK avec un message d’erreur dans le corps.
• Exposer directement la structure de la base (noms de tables, identifiants internes) au lieu de ressources pensées pour les clients.
• Vérifier les droits sur la route, mais pas sur l’objet demandé.
• Laisser des clés d’API dans le code source ou dans une application mobile.
• Livrer sans documentation, ou avec une documentation qui ne correspond plus au code.
• Oublier les tests automatisés des cas d’erreur, pas seulement du cas nominal.

Si vous devez connecter vos outils (CRM, facturation, site, e-commerce) ou exposer vos données à des partenaires, c’est le cœur de notre offre d’intégration et d’automatisation : une intégration API simple démarre à 1 500 €. Pour une plateforme complète, voyez nos applications web sur mesure. Et si vous recrutez plutôt en interne, notre article sur les questions à poser à un développeur d’API vous aidera.

Questions fréquentes

REST ou GraphQL ?

REST reste le choix le plus simple et le mieux outillé pour la plupart des API. GraphQL, créé chez Facebook et aujourd’hui gouverné par la GraphQL Foundation, est intéressant quand les clients ont besoin de composer finement les données qu’ils récupèrent.

Quel langage choisir pour développer une API ?

Celui que votre équipe maîtrise et saura maintenir : PHP (Laravel, Symfony), Node.js (Express), Python (FastAPI, Django), Java ou C#. Les bonnes pratiques ci-dessus sont les mêmes partout.

Faut-il versionner une API dès le départ ?

Oui, prévoir un /v1/ ne coûte rien et évite une migration pénible le jour où un changement majeur devient nécessaire.

Une clé d’API suffit-elle comme sécurité ?

Pour un échange entre deux serveurs, oui si elle circule en HTTPS, reste secrète et peut être révoquée. Dès qu’un utilisateur final est en jeu, préférez OAuth 2.0 et des jetons à durée limitée.

Combien de temps pour développer une API ?

Cela dépend du nombre de ressources, des règles métier et des systèmes à connecter. Le plus sûr est de rédiger d’abord le contrat OpenAPI : il permet d’estimer précisément la charge.

Sources

• Roy Fielding : Representational State Transfer (REST), chapitre 5 de sa thèse (2000)
• OpenAPI Initiative : OpenAPI Specification (version 3.2.1)
• IETF : RFC 9110, HTTP Semantics
• IETF : RFC 5789, méthode PATCH
• IETF : RFC 9457, Problem Details for HTTP APIs
• IETF : RFC 6585, code 429 Too Many Requests
• IETF : RFC 8259, format JSON
• IETF : RFC 6749, OAuth 2.0
• OWASP : API Security Top 10 2023
• MDN : codes de statut HTTP
• MDN : Cross-Origin Resource Sharing (CORS)
• GraphQL : FAQ