Meilleures pratiques pour le SDK client API

Générez le client de bas niveau à partir d'une spécification OpenAPI, et écrivez à la main uniquement une couche idiomatique fine par-dessus. Confiance : 0.85 Traitez la spécification API comme source de vérité et faites échouer l'intégration continue lorsque le code généré est obsolète. Confiance : 0.85 Rendez le premier appel possible en trois lignes : installer, créer un client avec une clé API, appeler une méthode. Confiance : 0.90 Lisez la clé API à partir d'une variable d'environnement bien connue par défaut, et ne la journalisez jamais ni ne l'incluez dans les messages d'erreur. Confiance : 0.95 Exposez des modèles de requête et de réponse entièrement typés, avec des types TypeScript ou des annotations de type Python inclus dans le package. Confiance : 0.90 Renvoiez des erreurs typées avec le statut HTTP, le code d'erreur, le message et l'ID de requête, au lieu d'une exception générique. Confiance : 0.90 Répétez les requêtes idempotentes en cas de délai d'attente, de réponses 429 et 5xx avec un backoff exponentiel et une gigue, et respectez les en-têtes Retry-After. Confiance : 0.90 Envoyez automatiquement une clé d'idempotence sur les requêtes POST répétées lorsque l'API le prend en charge. Confiance : 0.80 Définissez des délais d'attente par défaut raisonnables et laissez les appelants remplacer les paramètres de délai d'attente et de répétition par client et par requête. Confiance : 0.85 Fournissez des itérateurs à pagination automatique pour que les utilisateurs puissent parcourir tous les résultats sans gérer eux-mêmes les curseurs. Confiance : 0.85 Prenez en charge les réponses en streaming avec des itérateurs asynchrones natifs ou des générateurs au lieu de callbacks. Confiance : 0.80 Proposez des clients synchrones et asynchrones dans les langages où les deux sont courants, partageant les mêmes modèles. Confiance : 0.75 Gardez les dépendances d'exécution minimales et évitez de contraindre les utilisateurs à une version spécifique de bibliothèque HTTP. Confiance : 0.85 Envoyez un en-tête User-Agent avec le nom du SDK, la version et l'environnement d'exécution pour que les propriétaires d'API puissent voir l'adoption et déboguer les problèmes. Confiance : 0.80 Suivez strictement le versionnage sémantique et documentez les changements cassants avec des exemples de migration dans le journal des modifications. Confiance : 0.90 Ne supprimez jamais une méthode dans une version mineure ; dépréciez-la d'abord avec un avertissement. Confiance : 0.85 Testez avec des fixtures HTTP enregistrées pour la rapidité et exécutez une suite plus petite contre un environnement sandbox réel chaque nuit. Confiance : 0.80 Exécutez la suite de tests sur chaque version d'environnement d'exécution prise en charge dans l'intégration continue, comme chaque LTS Node.js actif ou version Python. Confiance : 0.85 Placez des exemples de code exécutables dans le README et la documentation, et testez ces exemples dans l'intégration continue pour qu'ils ne deviennent jamais obsolètes. Confiance : 0.80 Exposez des hooks ou des middleware pour la journalisation, le tracing et les en-têtes personnalisés au lieu d'ajouter des options ponctuelles pour chaque besoin. Confiance : 0.75 Autorisez une URL de base personnalisée et un client HTTP personnalisé pour que les utilisateurs puissent pointer le SDK vers des proxys, des mocks ou des endpoints régionaux. Confiance : 0.80 Publiez les packages depuis l'intégration continue avec provenance et signatures de version, jamais depuis l'ordinateur portable d'un mainteneur. Confiance : 0.75