Vibe · Cas client · Developer Platform
Versionner l’API de Vibe sans dupliquer le produit
Une architecture TypeScript fondée sur une chaîne d’adaptateurs pour faire évoluer les contrats partenaires, générer la documentation à partir du code et retirer une ancienne révision sans modifier les suivantes.
Explorer la Developer Platform
Cas client · Mission freelance
Chez Vibe, les intégrations font partie du produit. La mission s’est déroulée au sein d’une équipe de sept personnes et a couvert les connecteurs partenaires ainsi que la Developer Platform, avec un travail particulier sur le versionnement de son API publique.
La mission
Étendre l’écosystème partenaire sans éclater le code
Vibe permet aux entreprises d’acheter, de piloter et de mesurer des campagnes de publicité sur la télévision connectée. Son écosystème comprend des intégrations avec des produits comme Clay, Fivetran, Adjust ou AppsFlyer, ainsi qu’une Developer Platform utilisable directement par d’autres équipes techniques.
L’équipe réunissait un manager technique, une PM et cinq développeurs full-stack indépendants. La mission couvrait plusieurs intégrations et la plateforme publique. Les interfaces combinaient React, Next.js et TypeScript, avec des services en NestJS et Rust. L’API devait couvrir les campagnes, les audiences, les créations publicitaires et le reporting, tout en laissant chaque partenaire adopter une nouvelle révision à son rythme.
Le périmètre
Couvrir le parcours d’intégration, de l’authentification à la documentation et aux tests, sans maintenir une copie du produit pour chaque révision.
- Faire évoluer le contrat public sans migration forcée de tous les partenaires.
- Conserver une seule implémentation courante de la logique métier.
- Produire la documentation OpenAPI à partir du code réellement déployé.
La contrainte
Une nouvelle révision ne devait pas devenir une nouvelle application
Une API partenaire vit plus longtemps que la plupart de ses écrans. Renommer un champ, enrichir une structure ou rendre une valeur obligatoire peut améliorer le produit courant tout en cassant une intégration qui n’évoluera que plusieurs mois plus tard.
Un ADR a donc fixé la règle avant l’implémentation : les contrats restent isolés par révision, chaque transformation cible uniquement la révision suivante et les services métier ne connaissent que le modèle courant. TypeScript rend les incompatibilités entre ces niveaux visibles pendant la vérification de types.
Contrats cloisonnés
Chaque révision possède ses propres types d’entrée et de sortie. Les services métier utilisent le modèle courant ; le typecheck signale les incompatibilités lorsque les contrats évoluent.
Transformations adjacentes
Une ancienne requête passe de V1 à V2, puis de V2 au modèle courant. Aucun adaptateur ne doit connaître toutes les versions.
Retrait ciblé
Après dépréciation et disparition du trafic V1, son retrait couvre les routes, les adaptateurs d’entrée et de sortie, les schémas, les tests et la documentation. V2 et les révisions suivantes restent inchangées.
Documentation alignée
L’en-tête de révision, les schémas et les erreurs de chaque version sont décrits par la spécification OpenAPI produite depuis la même base de code.
Le versionnement est ainsi devenu un graphe de dépendances explicite. Une révision dépend uniquement de la suivante, et toutes convergent vers le même comportement métier.
Le choix d’architecture
Convertir chaque requête vers le modèle courant
Le partenaire épingle la révision qu’il utilise avec l’en-tête X-Vibe-Revision. La requête est validée avec le contrat correspondant, puis traverse une suite de petits adaptateurs jusqu’au format courant. Le service applicatif reçoit donc toujours le même type, quelle que soit la révision demandée.
Les types d’entrée et de sortie de chaque adaptateur sont explicites. Si la sortie de V1 ne correspond plus à l’entrée de V2, la compilation échoue. Ce contrôle détecte les ruptures de contrat, mais n’empêche pas à lui seul des imports inappropriés ni un contournement volontaire du typage : le découpage des modules, le lint et la review complètent le typecheck.
Contrat public révisé · TypeScript
Authentification, validation et types propres à la révision demandée par le partenaire.
Adaptateurs adjacents · V1 → V2 → courant
Transformations courtes dont l’entrée et la sortie sont contrôlées par le compilateur.
Services métier courants · NestJS / Rust
Une seule implémentation pour les campagnes, audiences, créations et données de reporting.
Exécution · Kubernetes / AWS / Cloudflare
Déploiement de la plateforme tout en conservant un contrat public stable.
type Adapter<From, To> = (input: From) => To
const v1ToV2 = ((input: V1.CreateCampaign) =>
mapV1ToV2(input)
) satisfies Adapter<V1.CreateCampaign, V2.CreateCampaign>
const v2ToCurrent = ((input: V2.CreateCampaign) =>
mapV2ToCurrent(input)
) satisfies Adapter<V2.CreateCampaign, Current.CreateCampaign>
const createFromV1 = (input: V1.CreateCampaign) =>
campaigns.create(v2ToCurrent(v1ToV2(input)))Cet exemple couvre uniquement l’adaptation d’une requête entrante : la logique de création ne reçoit que le contrat courant. En production, la réponse courante est ensuite projetée vers le contrat de sortie de la révision demandée. Supprimer V1 ne demande aucune modification de V2 ni du service métier de campagnes.
La mise en œuvre
Relier l’ADR, les tests, OpenAPI et la documentation publique
Le dispositif ne s’arrêtait pas aux types. Le mécanisme de versionnement devait rester facile à relire dans les pull requests, testable avec des comptes dédiés et compréhensible par un partenaire qui ne connaît pas l’organisation interne de Vibe.
01
Écrire les invariants dans un ADR
Le document fixe l’isolation des révisions, le sens des dépendances, la responsabilité des adaptateurs et les conditions de retrait.02
Segmenter les contrats dans le code
Les schémas et DTO sont rangés par révision. Ce découpage rend les imports entre versions visibles, tandis que TypeScript signale les signatures incompatibles.03
Générer la spécification OpenAPI à partir du code
La référence publiée sur developers.vibe.co provient de la spécification produite par le code. Le contrat et sa documentation sont ainsi mis à jour dans le même changement.04
Tester avec des données contrôlées
Des comptes réservés aux tests et des jeux de données synthétiques couvrent les parcours de campagne, d’audience, de création et de reporting.05
Contrôler chaque changement dans la CI
GitHub Actions exécute les vérifications avant le déploiement sur Kubernetes, AWS et Cloudflare. Chaque livraison reste soumise à la validation d’un membre de l’équipe.
Les types, les tests et la spécification OpenAPI maintiennent l’implémentation et la documentation publique alignées. La revue de l’équipe reste le dernier contrôle avant livraison.
Résultats
De quelques dizaines à environ une centaine de partenaires
Au cours de la mission, l’écosystème Vibe est passé de quelques dizaines à environ une centaine de partenaires. Le versionnement n’explique pas seul cette croissance. Il a cependant donné à l’équipe une API qu’elle pouvait étendre sans coordonner une migration générale à chaque changement.
Les intégrations dédiées et la Developer Platform ont fourni deux modes d’intégration complémentaires : connecter des produits tels que Clay, Fivetran, Adjust ou AppsFlyer, et permettre à d’autres partenaires d’intégrer directement les API publiques de Vibe.
Ce qui a été mis en place
Des éléments vérifiables dans le code, la documentation et la CI.
- Une API publique couvrant campagnes, audiences, créations publicitaires et reporting.
- Des révisions isolées et reliées par des adaptateurs TypeScript contrôlés à la compilation.
- Une logique métier courante partagée par toutes les révisions encore actives.
- Une documentation partenaire générée depuis OpenAPI et publiée sur developers.vibe.co.
- Des comptes de test, des données injectées et un pipeline GitHub Actions pour vérifier les changements.
La décision qui a tenu dans le temps
Chez Vibe, une ancienne version pouvait être retirée sans dupliquer le produit, car sa compatibilité reposait sur des adaptateurs vers le modèle courant.
Sources publiques et documentation
- Vibe Developer Platform. Vibe. Portail public de la plateforme et présentation des API REST destinées aux partenaires.
- API Versioning. Vibe Developer Platform. Documentation de l’en-tête de révision, de l’épinglage des appels et de la politique de compatibilité.
- Vibe API Reference. Vibe Developer Platform. Référence publique des ressources de campagne, de création, d’audience et de reporting.
- Introducing the Vibe Developer Platform. Vibe. Présentation officielle des intégrations en libre-service et des capacités intégrées aux produits partenaires.