Adresse de l’API et environnements

L’API Sursa a sa propre adresse, distincte de celle qu’utilisent les personnes pour ouvrir Sursa dans le navigateur. Tous les chemins commencent par /v1.

Où Sursa fonctionne	Adresse de l’API	Ce portail
Cloud Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Votre propre installation	`https://api.<your domain>`, selon la configuration de votre administrateur	`/developers/` sur l’adresse de l’API
Votre installation sans adresse d’API distincte	l’adresse principale de l’installation	`/developers/` sur l’adresse principale

L’adresse de l’API ne sert que l’API : elle n’a ni page de connexion, ni cookies, ni interface web. Chaque requête est authentifiée par une clé API ou par un jeton d’accès OAuth. L’adresse peut être servie par plusieurs serveurs derrière un répartiteur de charge ; votre intégration n’a pas besoin de savoir combien il y en a.

Les intégrations qui appellent l’API sur l’adresse principale (par exemple https://app.sursa.com/v1) continuent de fonctionner. Voir Passer à l’adresse de l’API pour les quelques différences et une migration pas à pas.

URL de base

Construisez chaque requête à partir d’une seule URL de base définie dans votre configuration : le même code fonctionne ainsi dans n’importe quel environnement.

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

N’utilisez que HTTPS et gardez la clé hors des journaux des requêtes que vous envoyez.

Version et spécification

GET /v1/health indique si l’adresse fonctionne et renvoie la version de Sursa qui la sert. Ce point de terminaison répond sans clé : vous pouvez donc l’utiliser dans votre supervision.

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Il s’agit de la version de la publication Sursa, et non de celle de l’API. La version de l’API est info.version de sa spécification. La spécification OpenAPI 3.1 de l’API est publiée à la même adresse, sans authentification :

Chemin	Contenu
`GET /openapi.json`	La spécification publique, avec cette adresse dans `servers`.
`GET /v1/openapi-public.json`	La même spécification. Prend en charge `ETag` et `If-None-Match`.

Utilisez-la pour générer un client, pour importer l’API dans un outil comme Postman ou pour vérifier en CI que votre intégration n’utilise que des opérations de la version attendue. La référence de l’API de ce portail est construite à partir du même fichier.

Tests

Sursa n’a pas de mode test distinct : chaque requête faite avec une clé agit sur les données réelles de son organisation. Pour développer et tester sans risque :

Créez une clé distincte pour le développement, avec le rôle et les portées les plus restreints dont le travail a besoin.
Écrivez dans une collection dédiée, par exemple sandbox, que seule votre équipe peut voir, et supprimez-la quand vous avez terminé.
Si votre entreprise dispose d’une organisation ou d’une installation Sursa distincte pour les tests, faites pointer l’URL de base et la clé vers elle. Rien d’autre ne change dans votre code.
Rendez les nouvelles tentatives sûres dès le départ : envoyez une clé d’idempotence avec chaque POST et PATCH.

La console Essayer de chaque page de point de terminaison de la référence de l’API envoie de vraies requêtes avec une clé que vous y collez. La clé reste dans la mémoire de l’onglet du navigateur et n’est envoyée qu’à l’adresse de l’API.

Prérequis réseau

HTTPS sortant (port 443) de vos serveurs vers l’adresse de l’API.
Dans les règles du pare-feu, autorisez le nom d’hôte plutôt que des adresses IP fixes quand votre réseau le permet : les serveurs derrière l’adresse peuvent changer à mesure que la capacité augmente.
Les applications dans le navigateur peuvent appeler l’API directement : les réponses autorisent toutes les origines (Access-Control-Allow-Origin: *), sans cookies. Gardez à l’esprit qu’une clé utilisée dans un navigateur est visible de l’utilisateur de ce navigateur.