L’API REST

Chaque chemin de cette page se place derrière l’URL de base ci-dessous, et chaque requête transporte votre clé dans un en-tête Authorization. Il n’y a pas d’autre entrée : pas de cookie de session, pas d’authentification basique, pas de clé dans la chaîne de requête.

curl -s https://app.provibr.com/api/v1/me \
  -H "Authorization: Bearer pvk_..."

Vous créez une clé sur votre propre page de profil, sous « Clés d’API ». Elle vous appartient et n’appartient qu’à un seul compte : elle n’est pas partagée avec vos collègues, et elle cesse de fonctionner dès que vous quittez ce compte.

• Une clé expire au bout de 90 jours, sauf choix contraire. Vous pouvez retenir une durée plus courte, ou aucune ; une clé sans date de fin est une clé que vous devez penser à révoquer vous-même.
• La rotation consiste à créer une nouvelle clé et à révoquer l’ancienne, avec un moment intermédiaire où les deux fonctionnent. On ne peut pas remplacer le secret d’une clé existante sur place, car cela vous laisserait sans clé utilisable si quelque chose tournait mal à mi-parcours.
• Vous pouvez lier une clé à une liste d’adresses. Une requête venue d’ailleurs est refusée avant que quoi que ce soit ne soit lu, et ce refus n’apprend rien à l’appelant sur la clé.
• Un membre détient au maximum 25 clés. Une clé révoquée conserve sa ligne : vous pouvez donc voir après coup ce qu’elle avait le droit de faire de son vivant.

Une clé porte des droits : lecture ou écriture, par partie du panneau. Ce qu’elle peut réellement faire est l’intersection de ces droits et de ceux du membre à qui elle appartient.

Les droits sont lus en direct, à chaque requête. Retirez quelque chose à un membre et toutes ses clés se restreignent aussitôt, sans que personne ait à révoquer quoi que ce soit. C’est aussi pour cela qu’une clé survit à un changement de rôle au lieu d’être invalidée par lui.

Votre infrastructure n’est joignable que par l’agent installé dans votre propre réseau, et cet agent se connecte vers l’extérieur. Un endpoint qui modifie une machine ne peut donc pas répondre par le résultat : il répond que l’ordre a été accepté et vous remet de quoi en suivre la suite.

1. 01Vous envoyez la requête et recevez une réponse d’acceptation, avec un en-tête Location qui pointe vers la commande créée. Cet en-tête est absolu à partir de l’hôte : résolvez-le par rapport à l’origine et non par rapport à l’URL de base ci-dessus, sous peine de demander un chemin qui n’existe pas.
2. 02Cette même commande figure aussi dans le corps, mais enveloppée dans un champ command. La relecture ci-dessous la renvoie nue, sans cette enveloppe : déballez-la une fois et la première relecture devient le plus souvent inutile.
3. 03Vous relisez la commande jusqu’à ce que son statut soit définitif : terminée, échouée, expirée ou annulée. Seul en attente ne l’est pas, et un statut que vous ne connaissez pas compte lui aussi comme définitif, si bien qu’une valeur ajoutée plus tard ne vous laissera jamais relire indéfiniment.
4. 04Une commande échouée porte le code d’erreur de l’agent lui-même, avec ses paramètres, les mêmes que ceux que le panneau affiche à votre écran.

# 1. the order - answers 202 with a Location header
curl -s -D - -X POST https://app.provibr.com/api/v1/servers/<serverId>/actions/start \
  -H "Authorization: Bearer pvk_..."

# 2. the outcome - repeat until the status is final
curl -s https://app.provibr.com/api/v1/commands/<commandId> \
  -H "Authorization: Bearer pvk_..."

Chaque point de terminaison indique ce qu’il renvoie : 200 pour une lecture, 201 lorsqu’une ressource a été créée, 202 lorsque votre agent a encore du travail. Et tous décrivent le corps qu’ils renvoient, avec un nom propre par ressource, si bien que le code que vous générez contient un type par ressource et non un par point de terminaison.

Les listes répondent par une page et un curseur ; vous renvoyez ce curseur jusqu’à ce qu’il revienne vide. Une page contient 50 lignes par défaut, et 100 au maximum.

Toute réponse qui n’est pas un succès a la même forme, quelle que soit la nature du problème et quel qu’en soit l’endroit.

{
  "error": {
    "code": "validation_failed",
    "message": "Name is too long (max 64).",
    "detail": "server.validation.apiKeys.nameTooLong",
    "params": { "max": 64 },
    "requestId": "3f9c1b2a-..."
  }
}

code

Le mot sur lequel brancher votre code. Il vient d’une liste fermée : une valeur que vous ne connaissez pas signifie donc que vous parlez à une version plus récente que celle pour laquelle vous avez développé.

message

Une phrase en anglais, pour qui lit un journal. N’y branchez jamais votre code : la formulation peut changer à tout moment.

detail

Un identifiant stable, lorsqu’il y en a un. C’est celui que le panneau utilise pour composer son propre message : vous pouvez donc rédiger la phrase dans votre langue.

params

Les paramètres qui accompagnent cet identifiant : une limite dépassée, un nom déjà pris, l’hôte qui a refusé.

requestId

L’identifiant de cette requête, présent aussi dans un en-tête de réponse. Citez-le lorsque vous nous interrogez sur quelque chose.

Vous pouvez faire 120 requêtes par minute et par clé, et 600 par compte, toutes clés confondues. Cette seconde limite existe pour que vingt clés ne puissent pas imposer vingt fois la charge au même hôte.

Tout ce qui crée quelque chose accepte un en-tête idempotency-key que vous composez vous-même. Répétez la même requête avec la même valeur et vous récupérez le premier résultat, au lieu d’une deuxième machine, d’une deuxième clé ou d’une deuxième commande.

Vous pouvez aussi envoyer votre propre x-request-id. Il revient dans la réponse et apparaît dans nos journaux : c’est le moyen le moins coûteux de poser une ligne de votre côté à côté d’une ligne du nôtre.

Il n’y a pas un seul nom de fournisseur dans le routage de cette API. Quels systèmes vous pouvez connecter, quels champs leurs identifiants comportent et ce dont ils sont capables : c’est l’endpoint de découverte qui répond, et le corps que vous envoyez pour créer une intégration est construit à partir de ce même registre. Un fournisseur qui entre en service apparaît dans les deux sans qu’un seul endpoint change.

Cela fonctionne aussi dans l’autre sens. Demandez à une machine quelque chose que son fournisseur ne sait pas faire (une console sur un compte d’hébergement, un disque sur un serveur de jeu), et vous obtenez un refus qui nomme la capacité manquante, avant que quoi que ce soit ne parte vers votre agent.

Regroupés comme la spécification les regroupe. Chaque chemin vient après l’URL de base, et à côté figure le droit que l’endpoint exige ; là où rien ne figure, une clé valide suffit.

La même information sous la forme d’un document OpenAPI 3.1, généré à partir du code qui sert ces endpoints plutôt qu’écrit à côté. Confiez-le à un générateur de clients, à un éditeur ou à une suite de tests.

curl -s https://app.provibr.com/api/v1/openapi.json

Au sein de cette version, les changements sont des ajouts : nouveaux endpoints, nouveaux champs facultatifs, nouvelles valeurs dans une liste. Lisez avec indulgence les champs que vous ne connaissez pas, et ne traitez pas comme fatal un code d’erreur inconnu.