Die REST-API

Jeder Pfad auf dieser Seite liegt hinter der Basis-URL unten, und jede Anfrage trägt Ihren Schlüssel in einem Authorization-Header. Einen anderen Weg hinein gibt es nicht: kein Session-Cookie, keine Basic Auth, keinen Schlüssel im Query-String.

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

Einen Schlüssel legen Sie auf Ihrer eigenen Profilseite an, unter API-Schlüssel. Er gehört Ihnen und einem Konto: Er wird nicht mit Ihren Kollegen geteilt, und er hört auf zu funktionieren, sobald Sie dieses Konto verlassen.

• Ein Schlüssel läuft nach 90 Tagen ab, sofern Sie nichts anderes wählen. Sie können eine kürzere Frist nehmen oder gar keine; an einen Schlüssel ohne Enddatum müssen Sie selbst denken, wenn er widerrufen werden soll.
• Rotieren heißt: einen neuen Schlüssel anlegen und den alten widerrufen, mit einem Moment dazwischen, in dem beide funktionieren. Eine Rotation an Ort und Stelle gibt es nicht, denn dabei stehen Sie ohne funktionierenden Schlüssel da, wenn auf halbem Weg etwas schiefgeht.
• Sie können einen Schlüssel an eine Liste von Adressen binden. Eine Anfrage von anderswo wird abgelehnt, bevor irgendetwas gelesen wird, und diese Ablehnung verrät dem Aufrufer nichts über den Schlüssel.
• Ein Mitglied hält höchstens 25 Schlüssel. Ein widerrufener Schlüssel behält seine Zeile, Sie sehen also auch später noch, was er zu Lebzeiten durfte.

Ein Schlüssel trägt Scopes: Lesen oder Schreiben, je Bereich des Panels. Was er tatsächlich darf, ist die Schnittmenge dieser Scopes und der Berechtigungen des Mitglieds, dem er gehört.

Berechtigungen werden live gelesen, bei jeder Anfrage. Nehmen Sie einem Mitglied etwas weg, wird jeder Schlüssel dieses Mitglieds sofort enger, ohne dass jemand etwas widerrufen muss. Deshalb übersteht ein Schlüssel auch einen Rollenwechsel, statt durch ihn ungültig zu werden.

Ihre Infrastruktur ist nur über den Agenten in Ihrem eigenen Netz erreichbar, und dieser Agent verbindet sich nach außen. Ein Endpunkt, der eine Maschine verändert, kann deshalb nicht mit dem Ergebnis antworten. Er antwortet, dass der Auftrag angenommen wurde, und gibt Ihnen etwas zum Nachverfolgen.

1. 01Sie senden die Anfrage und bekommen eine Annahme zurück, mit einem Location-Header, der auf den angelegten Befehl zeigt. Dieser Header ist absolut ab dem Host: Lösen Sie ihn gegen den Origin auf und nicht gegen die Basis-URL oben, sonst fragen Sie einen Pfad ab, den es nicht gibt.
2. 02Derselbe Befehl steht auch im Body, dort aber in ein Feld command eingepackt. Das Lesen unten liefert ihn blank, ohne diese Verpackung: einmal auspacken, und das erste Lesen ist meist überflüssig.
3. 03Sie lesen den Befehl, bis sein Status endgültig ist: abgeschlossen, fehlgeschlagen, abgelaufen oder abgebrochen. Nur in Bearbeitung ist nicht endgültig, und ein Status, den Sie nicht kennen, gilt ebenfalls als endgültig, sodass ein später hinzugekommener Wert Sie nie ewig weiterlesen lassen kann.
4. 04Ein fehlgeschlagener Befehl trägt den Fehlercode des Agenten selbst, mit seinen Parametern, denselben, die das Panel auf Ihrem Bildschirm darstellt.

# 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_..."

Jeder Endpunkt sagt, womit er antwortet: 200 beim Lesen, 201 wenn etwas angelegt wurde, 202 wenn Ihr Agent noch daran arbeiten muss. Und jeder beschreibt den Body, den er zurückgibt, mit einem eigenen Namen je Ressource, sodass der Code, den Sie generieren, einen Typ je Ressource kennt statt einen je Endpunkt.

Listen antworten mit einer Seite und einem Cursor; diesen Cursor geben Sie zurück, bis er leer zurückkommt. Eine Seite fasst standardmäßig 50 Zeilen und höchstens 100.

Jede Antwort, die kein Erfolg ist, hat dieselbe Form, was auch immer schiefging und wo auch immer es schiefging.

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

code

Das Wort, auf das Sie verzweigen. Es stammt aus einer geschlossenen Liste; ein Wert, den Sie nicht kennen, bedeutet also, dass Sie mit einer neueren Version sprechen als der, gegen die Sie gebaut haben.

message

Ein englischer Satz, für alle, die ein Log lesen. Verzweigen Sie nie darauf: Die Formulierung darf sich ändern.

detail

Ein stabiler Schlüssel, wo es einen gibt. Es ist derselbe Schlüssel, den das Panel für seine eigene Meldung verwendet, Sie können den Satz also in Ihrer eigenen Sprache ausgeben.

params

Die Parameter, die zu diesem Schlüssel gehören: ein überschrittenes Limit, ein bereits vergebener Name, der Host, der abgelehnt hat.

requestId

Die Kennung dieser Anfrage, auch in einem Antwort-Header. Geben Sie sie an, wenn Sie sich mit einer Frage an uns wenden.

Sie dürfen 120 Anfragen pro Minute und Schlüssel stellen und 600 pro Konto über alle seine Schlüssel zusammen. Die zweite Grenze gibt es, damit zwanzig Schlüssel nicht die zwanzigfache Last auf denselben Host legen.

Alles, was etwas anlegt, akzeptiert einen selbst gewählten idempotency-key-Header. Wiederholen Sie dieselbe Anfrage mit demselben Wert, bekommen Sie das erste Ergebnis zurück statt einer zweiten Maschine, eines zweiten Schlüssels oder eines zweiten Befehls.

Sie dürfen auch einen eigenen x-request-id-Header senden. Er kommt auf der Antwort zurück und taucht in unseren Logs auf; das ist der billigste Weg, eine Zeile von Ihrer Seite neben eine Zeile von unserer zu legen.

Im Routing dieser API steht kein einziger Anbietername. Welche Systeme Sie anbinden können, welche Felder ihre Zugangsdaten haben und was sie können, beantwortet der Discovery-Endpunkt, und der Body, mit dem Sie eine Integration anlegen, ist aus demselben Register gebaut. Ein Anbieter, der live geht, taucht in beidem auf, ohne dass sich ein einziger Endpunkt ändert.

Es funktioniert auch andersherum. Verlangen Sie etwas von einer Maschine, deren Anbieter das nicht kann – eine Konsole auf einem Hosting-Konto, eine Festplatte auf einem Gameserver –, bekommen Sie eine Ablehnung, die die fehlende Fähigkeit benennt, bevor irgendetwas an Ihren Agenten geht.

Gruppiert, wie die Spezifikation sie gruppiert. Jeder Pfad folgt auf die Basis-URL, und daneben steht der Scope, den der Endpunkt verlangt; steht dort nichts, genügt ein gültiger Schlüssel.

Dieselben Angaben als OpenAPI-3.1-Dokument, erzeugt aus dem Code, der diese Endpunkte bedient, statt daneben geschrieben zu sein. Geben Sie es einem Client-Generator, einem Editor oder einer Testsuite.

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

Innerhalb dieser Version sind Änderungen Ergänzungen: neue Endpunkte, neue optionale Felder, neue Werte in einer Liste. Lesen Sie Felder, die Sie nicht kennen, nachsichtig, und behandeln Sie einen Fehlercode, den Sie nicht kennen, nicht als fatal.