Aller au contenu principal

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"
}
  • code est 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.
  • message est écrit pour être lu par une personne. Ne faites pas de correspondance dessus.
  • traceId identifie 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​

DomaineCe qu'on y trouve
OrganisationsLes organisations, leurs informations de facturation, et la création de votre organisation personnelle
ProjetsLes projets, leur cycle de vie (création, suppression, restauration) et les localisations où les créer
OpérationsLa progression d'une mutation asynchrone
MembresQui a accès à une organisation ou à un projet, et avec quel rôle
InvitationsUn accès proposé à une adresse qui ne l'a pas encore accepté
Clés d'APILes clés pour les scripts et la CI, bornées par leur sujet (personnelle, organisation ou projet)
AlertesCe que la plateforme a observé d'anormal, et où ces alertes sont envoyées
AuditCe qui a été modifié, par qui, et par quel moyen
SupportLes 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​