Vue d'ensemble de l'API
L'API REST sur laquelle SailOps fonctionne, ouverte ressource après ressource.
C'est l'API que le tableau de bord SailOps appelle. Tout ce qu'il sait faire est joignable ici, décrit par un seul document OpenAPI, avec une seule forme d'erreur et une seule façon de parcourir une collection.
Son ouverture est progressive. Les organisations, les projets, les membres, les invitations, les clés d'API, les alertes, les notifications, le journal d'audit et les tickets de support sont servis aujourd'hui. Les conteneurs, les bases de données, les gateways et le reste vivent encore dans l'API publique, qui continue de fonctionner exactement comme avant.
URL de base
https://app.sailops.io
Les chemins sont absolus et portent leur propre préfixe : une URL complète s'écrit https://app.sailops.io/api/v3/organizations. Tout est servi en HTTPS.
Authentification
Deux types d'identifiants sont acceptés :
- Cookie de session — posé à la connexion. C'est ce qu'utilise votre navigateur.
- Clé d'API — envoyée dans l'en-tête
X-Api-Key. Une clé appartient à vous (personnelle), à une organisation ou à un projet, et ce qu'elle atteint découle de ce sujet. Voir Clés d'API pour les détails.
La plupart des opérations acceptent les deux. Les quelques-unes qui ne le font pas — la gestion des clés elles-mêmes, par exemple — nécessitent une session ; la référence interactive indique les identifiants acceptés par opération.
Erreurs
Tout échec renvoie le même corps, quelle qu'en soit la cause :
{
"code": "NOT_FOUND",
"message": "That project does not exist, or you cannot see it.",
"traceId": "4b8f2c1e9a7d30f5"
}
codeest stable. Des codes sont ajoutés au fil du temps, jamais renommés ni supprimés — traitez donc un code inconnu comme une erreur générique de son statut HTTP, plutôt que d'échouer dessus.messageest écrit pour être lu par une personne. Ne faites pas de correspondance dessus.traceIdidentifie cette requête précise dans nos journaux. Citez-le quand vous signalez un problème.
Un échec REQUEST_VALIDATION porte en plus un tableau validations qui nomme chaque champ rejeté et pourquoi.
Les codes les plus fréquents : UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, REQUEST_VALIDATION, TOO_MANY_REQUESTS, INTERNAL. La liste complète, avec la signification de chacun, est dans la référence interactive sous ApiErrorCode.
Introuvable, et non interdit
Une ressource à laquelle vous n'avez pas accès répond 404, pas 403. Son existence est elle-même une information, que l'API ne révèle pas. Un 403 signifie que la ressource est bien là et que votre rôle n'atteint pas cette opération dessus.
Pagination
Les collections renvoient une page et, s'il y a une suite, un nextCursor opaque :
{
"items": [ /* … */ ],
"nextCursor": "eyJvIjoyMCwicyI6ImE5Zj…"
}
Renvoyez-le en ?cursor=… pour obtenir la page suivante, et arrêtez-vous quand il est absent. Le curseur est signé : ce n'est pas un nombre à calculer, et un curseur modifié est refusé.
?limit= fixe la taille de page, jusqu'à 200.
Ce que couvre chaque partie
| Domaine | Ce qu'on y trouve |
|---|---|
| Organisations | Les organisations, leurs informations de facturation, et la création de votre organisation personnelle |
| Projets | Les projets, leur cycle de vie (création, suppression, restauration) et les localisations où les créer |
| Opérations | La progression d'une mutation asynchrone |
| Membres | Qui a accès à une organisation ou à un projet, et avec quel rôle |
| Invitations | Un accès proposé à une adresse qui ne l'a pas encore accepté |
| Clés d'API | Les clés pour les scripts et la CI, bornées par leur sujet (personnelle, organisation ou projet) |
| Alertes | Ce que la plateforme a observé d'anormal, et où ces alertes sont envoyées |
| Audit | Ce qui a été modifié, par qui, et par quel moyen |
| Support | Les questions et incidents remontés au support SailOps |
Versionnage
De nouveaux champs et de nouvelles opérations peuvent apparaître à tout moment : analysez les réponses de façon défensive et ignorez ce que vous ne connaissez pas. Rien n'est supprimé ni renommé sans une nouvelle version de la ressource concernée.
Pour aller plus loin
- Référence des endpoints — toutes les opérations, par domaine
- Référence interactive — schémas et paramètres, explorables