> ## Documentation Index > Fetch the complete documentation index at: https://docs.arkatech.fr/llms.txt > Use this file to discover all available pages before exploring further. # Bonnes pratiques > L'adoption de standards et de conventions clairs est cruciale pour transformer une simple interface en un contrat fiable pour vos consommateurs internes et externes. # 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éthode** | **Description** | **Avantages** | **Inconvé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ête** | La 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égorie** | **Plage de Codes** | **Signification** | **Exemples de Codes Clés** | | :----------------- | :----------------- | :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Succès** | 2xx | La 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). | | **Redirection** | 3xx | Une action supplémentaire doit être prise par le client pour compléter la requête. | `301 Moved Permanently`, `307 Temporary Redirect`. | | **Erreur Client** | 4xx | L'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 Serveur** | 5xx | L'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 ``` ```json theme={null} { "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 ``` ```json theme={null} { "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