Savoir qu'un hôte de compatibilité existe est une chose. Savoir exactement comment y déplacer une intégration existante, sans rien casser en chemin, en est une autre. Nous avons créé un ensemble dédié de guides de migration pour combler cet écart, regroupés sur /docs/compatibility/.
Les guides détaillent les étapes pratiques du changement : ce qui change dans une requête, ce qui reste identique, quelle méthode d'authentification utiliser et à quoi faire attention dans la réponse, fournisseur par fournisseur, endpoint par endpoint. Comme chacun de nos dix-sept hôtes de compatibilité reproduit exactement la forme des requêtes et des réponses de son fournisseur d'origine, hormis les textes de copyright, de conditions et de confidentialité, les guides se concentrent surtout sur ce qui diffère réellement : le nom d'hôte vers lequel pointer, la clé à générer et les en-têtes de quota qui accompagnent désormais chaque réponse.
Nous les avons rédigés pour un lecteur précis : quelqu'un qui dispose déjà d'un code fonctionnel avec un autre fournisseur et qui veut une certitude, pas seulement une promesse, que le faire pointer vers nous continuera de fonctionner. Cela implique aussi d'être explicite sur les tarifs pendant la transition. Chaque endpoint et chaque hôte de compatibilité coûtent le même prix, avec 2 500 requêtes gratuites par jour depuis n'importe quelle adresse et 2 500 requêtes gratuites supplémentaires par jour et par clé : tester une migration ne coûte donc rien avant de vous engager.
Chaque guide couvre aussi les petits détails qui ont tendance à faire trébucher une migration s'ils ne sont pas traités : la façon dont les requêtes par lots sont comptées, puisqu'un appel groupé compte chaque élément individuellement et non l'appel dans son ensemble, et la signification des en-têtes de quota supplémentaires de chaque réponse si vous ne les avez jamais vus. Rien de tout cela ne demande de deviner une fois le guide correspondant ouvert à côté de votre code.
Pour une équipe qui se demande s'il faut migrer, la démarche recommandée est simple : lisez le guide du fournisseur que vous utilisez actuellement, générez une clé et testez quelques requêtes réelles sur l'hôte compatible avant de toucher au moindre code de production. Comme le quota gratuit couvre entièrement ces tests, comparer les deux côte à côte avant de décider ne coûte rien.
La liste complète des hôtes de compatibilité couverts par ces guides se trouve sur /compatibility/, et la documentation générale sur l'authentification et les limites de débit, valable pour tous, se trouve sur /docs/authentication/ et /docs/rate-limits/. Nous prévoyons de continuer à enrichir cette collection de guides à mesure que la couverture de compatibilité s'étend.