Versioning API
Comment System One versionne l’API de décision et quels en-têtes envoyer depuis le SDK TypeScript.
L’API HTTP hébergée de System One et le SDK TypeScript autonome ont des limites de version distinctes. Cette page explique ce que contrôle chaque version et comment mettre à jour sans perdre la trace des requêtes en cours.
Prêt pour les questions
Comment fonctionne le versioning de l’API System One ? System One versionne l’API de décision hébergée par ses chemins HTTP documentés et le contrat de compatibilité publié ; il n’existe pas d’en-tête de négociation de version. Épinglez une version en production et suivez cette page pour les mises à niveau.
Stratégie de version
| Frontière | Comportement actuel |
|---|---|
| Chemin de l’API HTTP | Les décisions et l’extraction utilisent POST /v1/systemone (extraction quand fields est présent) ; la découverte des modèles utilise GET /v1/models public. Il n’existe pas d’endpoint de décision /v2. |
| Contrat maintenu | typesafe-2026-09-18 identifie l’instantané de compatibilité documenté. GET /api/system-one/config le renvoie comme contract ; ce n’est ni un identifiant de modèle ni un en-tête d’épinglage. |
| Version des paquets SDK | Les paquets sont publiés indépendamment. Les exemples hébergés utilisent core@0.8.0, transport-fetch@0.8.0 et adapter-system-one@0.7.0 (tous résolvent core@^0.8.0). Une mise à jour de paquet ne modifie pas /v1. |
| Modèle demandé | L’identifiant demandé, un éventuel alias et le model résolu renvoyé sont distincts des versions HTTP et SDK. Un alias peut changer au fil du temps. |
En-têtes
Il n’existe pas d’en-tête de négociation de version. Le code actuel ne définit ni en-tête de version de requête, ni en-tête de réponse Deprecation ou Sunset, ni période de préavis fixe. Le chemin HTTP, le contrat publié et la version du paquet SDK portent le versionnement.
Les en-têtes que vous envoyez restent ceux de l’authentification et du contrat :
POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/jsonGardez https://system-one.dev/v1 explicite pour l’adaptateur System One. Le client officiel @typesafe-ai/sdk@0.6.0, maintenu indépendamment, utilise une URL de base sans /v1 (https://system-one.dev), car il fournit lui-même le chemin. Les deux utilisent votre clé System One pour se connecter à ce service hébergé. Les adaptateurs directs d’un fournisseur utilisent leurs propres endpoints et leurs propres identifiants, et n’impliquent pas que ce fournisseur figure dans le catalogue hébergé. Voir Documentation du SDK.
Valeurs par défaut du SDK
Installez des versions explicites :
npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0Core 0.8 exporte ImageInput, l’images optionnel de premier niveau et l’extraction Clairic extract({ state, fields }). systemOneAdapter@0.7.0 encode les requêtes d’extraction, images comprises, et n’encode toujours pas les images d’evaluate(). Les images de décision hébergées passent donc par Fetch/HTTP, et les images Clairic par extract(). Vérifiez image dans capabilities.inputs, limits.images et limits.bytes plutôt que de déduire une capacité d’une version de paquet.
Ruptures et ajouts
Aucune période de préavis de dépréciation, date de fin de vie de l’API ou SLA de support n’est publiée. Le service n’émet pas actuellement d’en-têtes Deprecation ou Sunset ; leur absence ne garantit pas une compatibilité indéfinie. Aucune mise à niveau automatique, aucune disponibilité permanente des anciens modèles et aucun avis systématique de chaque changement de modèle ne sont promis. Pour les changements prévus, contactez support@system-one.dev.
Le client doit valider les champs de réponse qu’il utilise et tolérer les champs supplémentaires. Les comptes de jetons optionnels restent inconnus lorsqu’ils manquent ou sont null, jamais zéro. N’ajoutez pas de champs synthétiques warnings, rounding ou de comptabilité. Core renvoie un résultat typé normalisé ; le HTTP natif et le client TypeSafe officiel exposent une autre forme. Utilisez Fetch ou withResponse() du client officiel pour lire les en-têtes bruts.
Conseils de migration
Lors d’une mise à jour des paquets SDK, consultez le guide du SDK, les champs de requête de l’API et le guide de migration 0.6. L’ancien paquet @system-one-ai/sdk@0.5.3 est déprécié ; les exemples actuels utilisent des paquets core, adapter et transport séparés. Gardez les versions d’installation explicites et évaluez des questions représentatives avant de basculer un flux en production. Une migration de paquet ne change pas le chemin HTTP public.
Terminer les opérations en cours
L’idempotence est scopée au compte et à la requête canonique, y compris le modèle demandé effectif. Une opération non résolue doit conserver la même clé, le même modèle et le même corps pendant la récupération. Changer le modèle, l’échelle ou une autre entrée significative sous la même clé renvoie 409 idempotency_conflict.
Un modèle différent est une nouvelle opération et exige une nouvelle clé. La protection de rejeu dure 24 heures à partir de la création de la requête ; après ce délai, une ancienne clé peut démarrer une nouvelle opération facturable.
Liens internes : Référence API, Documentation du SDK, Codes d’erreur API, Clé d’idempotence.