Passer à l’adresse de l’API

Les intégrations plus anciennes appellent l’API sur l’adresse principale de Sursa, celle que les gens ouvrent dans le navigateur, par exemple https://app.sursa.com/v1/…. L’API dispose désormais aussi de sa propre adresse, https://api.sursa.com dans le cloud ou https://api.<your domain> dans votre installation. Elle est conçue pour les intégrations : elle monte en charge derrière un répartiteur de charge et ne sert rien d’autre que l’API.

Vous n’êtes pas obligé de migrer. L’adresse principale continue de servir /v1 pour les intégrations existantes, sans date de fin ni redirection. Migrez quand cela vous convient, pour profiter des avantages de l’adresse de l’API, et utilisez-la pour toute nouvelle intégration.

Ce qui ne change pas

Les chemins, les paramètres, les champs, les codes d’erreur et les événements : GET /v1/cards est la même requête sur les deux adresses.
Les clés API. Les mêmes clés kb_ et kbsrc_ fonctionnent sur les deux adresses, avec le même rôle, les mêmes portées et le même profil de données.
Les clés d’idempotence, les limites de débit et les quotas. Les requêtes faites sur les deux adresses comptent dans les mêmes quotas de l’organisation.
Les webhooks. Les livraisons, les signatures et les secrets ne dépendent pas de l’adresse que vous appelez.
Les liens des réponses. Le doc_url d’une erreur pointe vers ce portail, et l’en-tête Link d’une page de liste pointe vers l’adresse de l’API, quelle que soit l’adresse que vous appelez.

Ce qui diffère sur l’adresse de l’API

Sur l’adresse principale	Sur l’adresse de l’API
Tous les points de terminaison de l’application web, y compris les points de terminaison internes	Uniquement les points de terminaison de la référence publique de l’API. Tout autre chemin répond `404` avec le code `api.not_found`.
Une clé dans `X-API-Key` ou `Authorization`, ou un cookie de session du navigateur	Une clé ou un jeton d’accès OAuth, de préférence dans `Authorization: Bearer`. Les cookies sont ignorés.
`GET /auth/me`	`GET /v1/me`. Les chemins sous `/auth/` ne sont pas servis.
Le mode « View as » (voir en tant que) par cookie	L’en-tête `X-View-As`, pour les clés dotées du rôle `admin`.
Un serveur, ou un ensemble fixe de serveurs	Plusieurs serveurs derrière un répartiteur de charge.

La dernière ligne ne compte que dans un cas : une réponse en flux de POST /v1/chat. Un flux interrompu ne reprend à partir de Last-Event-ID que sur le serveur qui rédige la réponse. Si votre intégration reprend les flux, donnez à chaque question un request_id : une nouvelle tentative sur un autre serveur reçoit alors la réponse enregistrée au lieu d’une seconde réponse. Voir Reprendre un flux interrompu.

Avant de migrer

Vérifiez que chaque appel est public. Listez les chemins qu’appelle votre intégration et cherchez chacun d’eux dans la référence de l’API, ou comparez-les avec la spécification de la nouvelle adresse :

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Un chemin absent de la référence publique appartient à l’application web. Il fonctionne toujours sur l’adresse principale, mais il n’est pas servi sur l’adresse de l’API, et sa forme ne constitue pas un engagement public. Remplacez-le par un point de terminaison public, ou gardez cette partie de l’intégration sur l’adresse principale et indiquez votre besoin à votre interlocuteur chez Sursa.

Vérifiez votre mode d’authentification. Si l’intégration se connecte avec le mot de passe d’un utilisateur et un cookie de session, faites-la d’abord passer à une clé API. Si elle envoie X-API-Key, il est recommandé, mais pas obligatoire, de passer à Authorization: Bearer.

Vérifiez votre réseau. Autorisez le HTTPS sortant vers le nouveau nom d’hôte dans votre pare-feu et vos proxys.

Migrer pas à pas

Faites de l’URL de base un paramètre de votre intégration, si ce n’est pas déjà le cas.

Essayez la nouvelle adresse avec une requête de lecture :

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Exécutez la suite de tests de votre intégration sur la nouvelle adresse, avec une clé de test et une collection de test.
Basculez une partie du trafic, par exemple un processus ou un environnement, et surveillez 404 api.not_found, 401 et 5xx dans vos journaux. Chaque réponse porte X-Request-Id ; conservez-le avec vos journaux.
Basculez le reste. Gardez quelque temps l’ancienne URL de base dans votre configuration pour pouvoir revenir en arrière en quelques secondes.

Points à vérifier après la migration

GET /v1/health sur la nouvelle adresse renvoie la même version que sur l’ancienne.
Les en-têtes RateLimit sont présents dans les réponses. Si votre intégration règle son rythme sur X-RateLimit-*, elle peut continuer à le faire : les deux jeux d’en-têtes sont envoyés. Voir Limites de débit et quotas.
Si votre intégration tourne dans un navigateur, elle n’a plus besoin de votre propre proxy pour CORS : l’adresse de l’API accepte les requêtes de toutes les origines, sans cookies.