Le problème des clés d'API qui n'expirent jamais
Une clé émise il y a des années, jamais renouvelée et toujours valide aujourd'hui n'est pas une commodité. C'est un risque que personne n'a vraiment examiné depuis des années.
Pourquoi nous publions nos codes d'erreur au lieu de les cacher
Une requête d'API en échec est déjà un mauvais moment dans la journée de quelqu'un. C'est pire quand le code d'erreur renvoyé n'est expliqué nulle part et que le développeur qui le débogue doit deviner si un 400 signifie un paramètre mal formé, un champ obligatoire manquant ou tout autre chose qui partage par hasard le même code de statut que trois autres problèmes sans rapport. Une erreur non documentée n'est pas qu'un désagrément. Elle transforme une correction de cinq minutes en une enquête sans fin, qui se termine parfois par un ticket d'assistance qu'on aurait pu éviter en lisant une page qui aurait dû exister.
Nous publions clairement nos codes d'erreur dans la documentation des erreurs, en indiquant ce que chacun signifie réellement et ce qui le provoque le plus souvent, à côté des pages authentification et limites de débit qui décrivent les autres façons dont une requête peut échouer. L'objectif est que, lorsque quelque chose ne va pas, la réponse se trouve à une page de distance, et non dans une supposition fondée sur les conventions générales des codes de statut HTTP, qui peuvent correspondre ou non à ce que notre système a précisément fait.
Cacher les détails des erreurs, même involontairement par une documentation trop mince, vient parfois d'un réflexe qui semble raisonnable : exposer précisément pourquoi une requête a échoué pourrait en théorie aider quelqu'un qui sonde une API à la recherche de failles. En pratique, cette crainte résiste rarement au coût réel. L'immense majorité des personnes qui rencontrent un code d'erreur sont des développeurs légitimes qui essaient de corriger leur propre intégration, pas des adversaires qui cartographient une surface d'attaque. Concevoir la documentation des erreurs autour du rare acteur malveillant, au détriment de la clarté pour tous les autres, inverse le compromis.
Publier clairement les codes d'erreur apporte aussi un bénéfice de discipline de conception : cela impose une cohérence interne. Si chaque code d'erreur doit être documenté avec une explication simple, il devient beaucoup plus difficile d'accumuler un tas de conditions d'erreur improvisées et qui se chevauchent, que seul l'ingénieur qui les a écrites comprend entièrement. Rédiger la documentation constitue aussi, discrètement, une forme de revue de code de la gestion des erreurs elle-même, car une erreur difficile à expliquer clairement est souvent le signe que la condition sous-jacente n'a pas été bien réfléchie au départ.
Les échecs liés au quota bénéficient d'un traitement voisin, par les en-têtes de réponse plutôt que par les seuls codes d'erreur. Chaque réponse indique votre limite de quota, votre consommation, le quota gratuit restant, la consommation de votre réseau, le crédit restant et l'heure de réinitialisation, si bien qu'une requête qui échoue à cause du quota n'a rien d'un code de statut mystérieux. C'est un nombre que vous auriez pu vérifier avant d'envoyer la requête, et que vous pouvez lire directement dans la réponse en échec.
Rien de tout cela ne supprime la frustration d'une requête en échec. Cela signifie simplement que la frustration doit s'arrêter à la documentation, avec une vraie réponse, au lieu de se prolonger dans une file d'assistance ou un jeu de devinettes à travers de vieux messages de forum sur ce qu'un code de statut d'une API complètement différente aurait pu signifier dans une situation apparemment similaire.