Gérer les versions d'endpoint

Cette compétence est un guide pratique du versioning d'endpoint. Elle couvre le workflow actuel, qui comporte quelques aspérités worth d'être explicites.

Quand utiliser cette compétence

• « Comment revenir à la v3 ? »
• « Je veux tester les modifications avant qu'elles ne soient en production »
• « Comment mettre à jour la description / data_freshness_seconds sur une version spécifique ? »
• « Puis-je désactiver v4 sans affecter v5 ? »
• L'utilisateur n'est pas certain si une modification de requête créera une nouvelle version

Modèle de versioning — ce qu'il faut savoir

Le modèle est unidirectionnel. Il n'y a pas d'opération « rendre v3 le défaut à nouveau » aujourd'hui. Pratiquement, cela signifie que « revenir » requiert soit de créer une nouvelle version supérieure qui réutilise l'ancienne requête, soit d'épingler les appelants à ?version=N.

Outils disponibles

Workflows

Prévisualiser un brouillon avant de publier

Il n'y a pas de concept de « brouillon » dans le modèle. Éditer la requête la valide comme une nouvelle version immédiatement. Pour prévisualiser en toute sécurité :

1. Teste d'abord la nouvelle requête avec l'outil execute-sql (ou l'éditeur SQL) — pas sur l'endpoint en production
2. Quand c'est prêt, mets à jour l'endpoint — cela crée la nouvelle version automatiquement
3. Utilise endpoint-run avec ?version=N pour confirmer que la nouvelle version renvoie ce que tu attends
4. Les anciens appelants frappent toujours la version la plus récente (qui est maintenant ta nouvelle version) — il n'y a pas de « lancement en douceur »

Si l'utilisateur a besoin d'un vrai endpoint de staging, la seule contournade aujourd'hui est un endpoint frère avec un suffixe _v2 ou _staging. Documente cela honnêtement — il n'y a pas de chemin de staging dans le produit.

Revenir à une version plus ancienne

Le modèle unidirectionnel signifie que « revenir » requiert un fork :

1. endpoint-versions pour trouver la version avec la bonne requête (disons v3)
2. endpoint-get avec ?version=3 pour récupérer la requête JSON de cette version
3. endpoint-update avec la requête v3 comme nouvelle requête — cela crée une nouvelle version (par ex. v6) avec la même requête que v3
4. Tous les appelants sans ?version=N frappent maintenant v6 (== la requête de v3)

L'ancienne version (v5, la cassée) existe toujours et reste appelable via ?version=5 jusqu'à être explicitement désactivée.

Atténuation plus rapide si tu peux modifier chaque appelant : fais-les épingler à ?version=3 jusqu'à ce qu'un vrai correctif soit prêt. Moins d'impact que de créer une nouvelle version.

Mettre à jour les paramètres sur une version spécifique

endpoint-update accepte un champ version dans le body. Quand il est défini, les mises à jour de paramètres s'appliquent à cette version uniquement — elles ne créent pas de nouvelle version. Utile quand :

• Augmenter data_freshness_seconds sur une ancienne version que certains appelants épinglent toujours
• Ajuster la description sur une version historique pour la clarté
• Changer l'état de matérialisation par version (la matérialisation est par-version de toute façon)

Important : passer query avec version est rejeté — les modifications de requête créent toujours une nouvelle version supérieure, jamais de modification historique. L'argument version affecte uniquement les paramètres.

Désactiver une seule version

Pour retirer v3 du service tout en gardant v4 et v5 appelables :

endpoint-update {name: "...", version: 3, is_active: false}

Cela définit is_active: false sur v3 uniquement. Les appelants épinglés à ?version=3 commencent à recevoir une erreur ; les autres appelants ne sont pas affectés.

Pour réactiver : même appel avec is_active: true.

Le champ is_active de l'endpoint entier (sans version) est un interrupteur séparé — il désactive chaque version à la fois. Utilise la forme de portée de version pour les takedowns chirurgicaux.

Nettoyer les versions inutilisées

Les anciennes versions s'accumulent avec le temps. Pour trouver lesquelles sont mortes, appelle endpoint-versions et lis chaque last_executed_at de la version : une version qui est null ou longtemps stale n'a pas été appelée récemment. Les versions mortes matérialisées sont les coûteuses — désactive leur matérialisation avec endpoint-update + version + is_materialized: false, et désactive avec is_active: false pour signaler qu'elles sont retirées.

Confirme avec l'utilisateur avant de retirer une version : last_executed_at compte uniquement les appels de clé API personnelle et est enregistré uniquement pour les exécutions depuis que ce suivi a été ajouté (donc une version utilisée peut toujours lire null), et un appelant peut être épinglé à ?version=N. Le flux d'audit complet vit dans auditing-endpoints.

Interaction d'exemple

User: "J'ai déployé une requête cassée la nuit dernière, v5. Comment je reviens en arrière ?"

Agent:
- endpoint-versions <name> → v5 (latest), v4, v3, v2, v1
- endpoint-get <name> ?version=4 → query JSON for v4
- "Revenir en arrière signifie créer v6 avec la requête de v4. v5 reste comme une
   version historique mais personne ne la frappe sauf s'il passe explicitement
   ?version=5. C'est bon ?"
- User confirms
- endpoint-update <name> {query: <v4 query>} → creates v6
- endpoint-run <name> ?version=6 to confirm shape
- "C'est fait. v6 est en production avec la requête de v4. Tu veux que je désactive aussi v5
   pour que ce soit clair que c'est défunt ?"
- User: "Oui"
- endpoint-update <name> {version: 5, is_active: false}

Notes importantes

• Il n'y a pas de saut de pointeur. « Revenir en arrière » crée une nouvelle version. Le numéro de version monte toujours. Si l'utilisateur n'est pas à l'aise avec le bruit historique résultant, c'est une préoccupation juste — surface-la honnêtement.
• Une modification de requête crée toujours une nouvelle version. Mettre à jour les paramètres à côté ne le fait pas. Si l'utilisateur veut corriger une faute de frappe dans la description de v5 sans passer à v6, utilise le paramètre version.
• Désactiver une seule version ne bloque que cette version. Cela ne change pas la version qui s'exécute par défaut — c'est toujours le numéro de version le plus élevé.
• La matérialisation est par-version. Chaque version a sa propre vue matérialisée nommée {endpoint_name}_v{version}. Désactiver la matérialisation sur une version n'affecte pas les autres.
• L'épinglage est le filet de sécurité — pousse les appelants à l'utiliser. Les appelants qui épinglent à ?version=N sont isolés des éditions de requête ; les appelants non épinglés frappent toujours la plus récente et peuvent être surpris par une nouvelle version. Encourage les consommateurs à épingler, valider une nouvelle version, puis augmenter l'épingle délibérément.
• Le CLI gère aussi les versions. posthog-cli exp endpoints {pull,push,diff} laisse l'utilisateur garder les définitions d'endpoint en YAML dans le contrôle de version et revoir les modifications avant de pousser — un workflow plus propre que l'édition en direct quand les modifications de requête ont besoin d'examen.
• Activer une version plus ancienne n'est pas encore une fonctionnalité du produit. Si l'utilisateur le souhaite à maintes reprises — faire sauter un pointeur plutôt que de forker — surface-le comme un vide de fonctionnalité (et nudge l'équipe via agent-feedback). Ne prétends pas que endpoint-update le fait.