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.
Contre les formats de réponse propriétaires
Demandez pourquoi une API renvoie un modèle d'objet imbriqué et personnalisé au lieu d'une structure JSON simple et plate, et la réponse honnête est rarement technique. Une structure propriétaire ne rend pas une recherche plus rapide ni plus précise. Elle rend la réponse plus difficile à remplacer, car chaque nom de champ, chaque niveau d'imbrication et chaque code de statut personnalisé que votre code apprend à gérer est un petit morceau de connaissance propre au fournisseur, intégré à votre application.
Nous pensons que c'est le monde à l'envers. Un format de réponse devrait décrire les données, pas le fournisseur. Les coordonnées, les adresses, les décalages horaires et les altitudes sont les mêmes concepts, quel que soit celui qui répond à la requête, donc la structure renvoyée devrait être à peu près aussi simple que les concepts eux-mêmes. C'est aussi pourquoi 17 de nos hôtes renvoient exactement la structure de réponse de l'API d'un autre fournisseur : les données sont les nôtres, mais la structure est une structure que votre code comprend peut-être déjà, parce que ce n'était pas vraiment à nous de l'inventer au départ.
Les formats propriétaires ont aussi tendance à accumuler des bizarreries qui n'ont rien à voir avec les données sous-jacentes et tout à voir avec l'histoire interne d'un fournisseur. Un champ est renommé lors d'une migration interne et l'ancien nom subsiste comme alias obsolète que personne ne veut supprimer. Un statut est représenté par une chaîne dans un endpoint et par un code numérique dans un autre parce qu'ils ont été développés par des équipes différentes, à des années d'intervalle. Rien de tout cela n'est malveillant. C'est simplement ce qui arrive quand un format n'est jamais conçu par rapport à une norme externe, mais uniquement par rapport au code en constante évolution d'une entreprise.
La solution n'est pas compliquée : choisir une structure simple, la documenter une fois et la maintenir stable. C'est ce que nous faisons pour nos propres endpoints natifs, et nous allons un cran plus loin avec les hôtes de compatibilité, en reproduisant exactement la structure d'un autre fournisseur afin qu'un code qui analyse déjà cette structure n'ait besoin d'aucune modification au-delà d'une URL de base et d'une clé. C'est un engagement plus important qu'il n'y paraît. Cela signifie que lorsque la structure que nous reproduisons comporte un nom de champ maladroit ou un choix d'imbrication incohérent, nous conservons la maladresse, car toute la valeur de l'hôte de compatibilité réside dans la fidélité, pas dans l'amélioration.
Un format propriétaire est parfois défendu au motif qu'il laisse au fournisseur la possibilité d'ajouter des données plus riches au fil du temps. Nous ne pensons pas que la richesse exige une structure inconnue. Des champs optionnels, comme l'altitude ou le détail des menaces liées à une IP, peuvent s'ajouter à une réponse standard plutôt que la remplacer, de sorte qu'un appelant qui ne les demande pas n'a jamais à les contourner, et qu'un appelant qui les demande les obtient sans apprendre un nouveau format.
Il ne s'agit pas vraiment ici du formatage JSON en tant que préférence technique. Il s'agit de savoir qui supporte le coût d'une décision de structure. Un format propriétaire fait porter ce coût à chaque client qui doit un jour lire la réponse. Un format simple ou reproduit le fait porter sur nous, dans le travail de conception nécessaire pour que tout reste prévisible. C'est là que ce coût doit se trouver.