Contrat API v1
Routes, versionnement, compatibilité et ressources lisibles par machine d’Orbit v1.
Le document courant décrit la version candidate 1.0.0-rc.3 du dépôt. Les routes de recherche et de résolution ainsi que le socle de comptage mensuel sont déployés sur orbit-dev et orbit-prod. Les en-têtes mensuels apparaissent uniquement sur les accès libre-service Gratuit ou Pro ; ils restent absents des accès historiques ou complémentaires non mesurés. Le préfixe HTTP reste /v1 : la version du document peut progresser sans changer les routes ni les UUID Orbit. orbit-dev demeure la cible d’intégration par défaut et chaque environnement utilise ses propres clés.
Routes canoniques
GET /v1/interests/search
POST /v1/interests/resolveLa cible d’intégration par défaut de cette version est orbit-dev : https://anvhjdjxovzjnvpmjtkl.supabase.co/functions/v1/api. Dans cette URL, /functions/v1 appartient à la passerelle Edge Functions, api nomme la fonction canonique et le /v1 ajouté par les routes ci-dessus versionne le contrat Orbit. La production reste documentée à https://jsmxzmxgxwexgvaraeke.supabase.co/functions/v1/api, mais elle utilise un paquet de clés distinct remis seulement après validation du passage en production.
Authentification
Chaque requête canonique envoie une unique clé Orbit du même environnement, dotée des permissions nécessaires, dans Authorization: Bearer <ORBIT_API_KEY>. Elle est strictement serveur-à-serveur, révocable, renouvelable et soumise à des quotas minute/jour. Une limite dépassée produit 429 et Retry-After.
Orbit remet cette clé pendant l’intégration du client. Un consommateur n’a pas besoin d’accéder au tableau de bord Supabase et ne doit jamais substituer une clé Supabase publiable, secrète ou service_role. Consultez le guide d’authentification.
Chaque réponse métier renvoie aussi un X-Request-Id généré par Orbit. Le preflight CORS peut être traité directement par la passerelle Supabase sans cet en-tête. Communiquez uniquement l’identifiant d’une réponse métier lors d’un diagnostic ; il permet de corréler les journaux sans partager une clé ou le contenu de la requête.
Ressources
Compatibilité
Dans Orbit v1, les champs requis, les types, les états de résolution, les catégories et les limites ne sont pas retirés ou modifiés de façon incompatible. Les champs de réponse optionnels peuvent évoluer et les clients doivent ignorer ceux qu’ils ne connaissent pas.
Le classement de recherche peut évoluer : il ne constitue ni une pagination, ni une garantie d’ordre stable. Les routes de lecture sont réessayables sans effet de bord, mais les clients doivent respecter Retry-After et borner leurs tentatives.
La version générale 1.0.0 reste conditionnée à la publication d’un canal d’assistance, des conditions applicables et de l’origine API durable approuvés. Jusqu’à cette publication, la version candidate n’est accessible qu’aux clients explicitement intégrés par Orbit.