Skip to main content

​
Versioning des APIs

Le versioning est la pratique qui consiste à gérer les changements non rétrocompatibles dans votre API (par exemple, le retrait d’un champ ou la modification d’un chemin) sans casser les applications clientes existantes. Méthodes de Versioning
MéthodeDescriptionAvantagesInconvénients
Via l’URL (URI Versioning)La version est incluse directement dans le chemin de la ressource : /api/v1/produits.Clair et visible, très facile à mettre en cache et à router via des load balancers.Moins “RESTful” (l’URI ne devrait pointer que vers la ressource, pas son état).
Via l’En-tête (Header Versioning)Utilisation d’un en-tête HTTP personnalisé (ex: X-API-Version: 2) ou de l’en-tête Accept.Plus “RESTful”, l’URI reste propre et stable.Plus difficile à tester via le navigateur, requiert une configuration de mise en cache plus complexe.
Via les Paramètres de RequêteLa version est ajoutée comme paramètre : /api/produits?version=3.Idéal pour des changements mineurs (patchs) ou pour tester rapidement une nouvelle version.Confusion possible entre le versioning et les filtres de données (ex : ?status=active).
Recommandation L’approche la plus courante et la plus simple pour les APIs REST publiques est le Versioning via l’URL (/v1/). Elle offre la meilleure clarté et est la plus simple à mettre en œuvre.

​
Documentation (OpenAPI / Swagger)

La documentation est le contrat entre l’API et ses utilisateurs. Une documentation à jour, interactive et standardisée est non négociable. OpenAPI Specification (OAS) L’OpenAPI Specification (anciennement Swagger Specification) est une norme agnostique permettant de décrire la structure de votre API de manière standardisée et lisible à la fois par l’homme et par la machine. Avantages de l’OAS
  • Génération de Code : L’OAS permet de générer automatiquement des clients API (SDKs) dans n’importe quel langage (Java, Python, TypeScript, etc.).
  • Validation Automatique : Le schéma peut être utilisé pour valider les requêtes et les réponses au moment de l’exécution (runtime).
  • Documentation Interactive : L’OAS est la base des outils comme Swagger UI, qui transforment le fichier de spécification (JSON ou YAML) en une interface web interactive où les utilisateurs peuvent visualiser et tester l’API directement.
  • Design First : Adopter l’OAS permet une approche “Design First”, où l’API est conçue et validée avant même que le développement ne commence.
Outils Clés
  • Swagger UI : L’outil le plus populaire pour visualiser la documentation OAS.
  • Swagger Editor : Éditeur en ligne pour créer et valider les fichiers de spécification OAS.
  • Postman : Peut importer des fichiers OAS pour créer des collections de tests.

​
Gestion des Erreurs et Codes de Statut

Une gestion des erreurs cohérente et informative est essentielle pour aider les développeurs clients à déboguer rapidement leurs applications. Le standard repose sur l’utilisation correcte des Codes de Statut HTTP. Utilisation Standardisée des Codes de Statut HTTP
CatégoriePlage de CodesSignificationExemples de Codes Clés
Succès2xxLa requête a été reçue, comprise et acceptée.200 OK (Succès général), 201 Created (Nouvelle ressource créée), 204 No Content (Succès sans corps de réponse).
Redirection3xxUne action supplémentaire doit être prise par le client pour compléter la requête.301 Moved Permanently, 307 Temporary Redirect.
Erreur Client4xxL’erreur provient du client (mauvaise requête, mauvaise authentification, etc.).400 Bad Request (Format de requête invalide), 401 Unauthorized (Authentification requise/manquante), 403 Forbidden (Accès refusé, autorisation insuffisante), 404 Not Found (Ressource inexistante), 429 Too Many Requests (Limite de débit atteinte).
Erreur Serveur5xxL’erreur provient du serveur alors que la requête était valide.500 Internal Server Error (Erreur générique côté serveur), 502 Bad Gateway, 503 Service Unavailable.
Formatage des Réponses d’Erreur (RFC 7807) Pour les erreurs 4xx et 5xx, la bonne pratique est de fournir un corps de réponse structuré (souvent JSON) qui donne au client les détails nécessaires pour corriger son problème. Il est fortement recommandé de suivre le standard RFC 7807 (Problem Details for HTTP APIs), qui fournit un format standardisé : 
HTTP/1.1 403 Forbidden
Content-Language: en

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "Vous n'avez pas assez de crédit.",
  "detail": "Votre solde actuel est de 30, et le coût de l'opération est de 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": ["/account/12345",
               "/account/67890"]
  }
}
  • type: Un URI pointant vers un document décrivant le type d’erreur.
  • title: Un court résumé lisible de l’erreur.
  • detail: Détails spécifiques à l’occurrence du problème.
HTTP/1.1 400 Bad Request
Content-Language: en

{
   "type": "https://example.net/validation-error",
   "title": "Your request parameters didn't validate.",
   "invalid-params": [ {
                         "name": "age",
                         "reason": "must be a positive integer"
                       },
                       {
                         "name": "color",
                         "reason": "must be 'green', 'red' or 'blue'"}
                     ]
}
Bonnes Pratiques de Gestion d’Erreur
  1. Ne Jamais Exposer l’Interne : Ne retournez jamais de stack traces complètes, de noms de tables de base de données, ou d’autres informations sensibles.
  2. Cohérence : Utilisez toujours le même format d’erreur pour toutes les erreurs renvoyées par l’API.
  3. Être Précis : Pour les erreurs 400 Bad Request (requête invalide), détaillez exactement quels champs sont manquants ou mal formatés