De REST API

Elk pad op deze pagina hangt achter de basis-URL hieronder, en elk verzoek draagt je sleutel in een Authorization-header. Een andere ingang is er niet: geen sessiecookie, geen basic auth, geen sleutel in de querystring.

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

Je maakt een sleutel aan op je eigen profielpagina, onder API-sleutels. Hij is van jou en van één account: je collega's delen hem niet, en hij werkt niet meer zodra je dat account verlaat.

• Een sleutel verloopt na 90 dagen, tenzij je iets anders kiest. Je kunt een kortere termijn nemen, of helemaal geen; bij een sleutel zonder einddatum moet jij eraan denken hem in te trekken.
• Roteren doe je door een nieuwe sleutel aan te maken en de oude in te trekken, met een moment ertussen waarop ze allebei werken. Ter plekke roteren bestaat niet, want dan sta je zonder werkende sleutel zodra er halverwege iets misgaat.
• Je kunt een sleutel binden aan een lijst adressen. Een verzoek van ergens anders wordt geweigerd voordat er iets gelezen is, en die weigering vertelt de aanroeper niets over de sleutel.
• Één lid houdt hoogstens 25 sleutels. Een ingetrokken sleutel blijft als rij staan, zodat je achteraf nog kunt zien wat hij mocht toen hij leefde.

Een sleutel draagt scopes: lezen of schrijven, per onderdeel van het paneel. Wat hij werkelijk mag is de doorsnede van die scopes en de rechten van het lid van wie hij is.

Rechten worden live gelezen, bij elk verzoek. Neem je een lid iets af, dan wordt elke sleutel van dat lid meteen smaller, zonder dat iemand iets hoeft in te trekken. Daarom overleeft een sleutel ook een rolwijziging in plaats van erdoor ongeldig te worden.

Je infrastructuur is alleen bereikbaar via de agent in je eigen netwerk, en die agent verbindt uitgaand. Een endpoint dat een machine wijzigt kan dus niet met de uitkomst antwoorden. Het antwoordt dat de opdracht is aangenomen, en geeft je iets om te volgen.

1. 01Je stuurt het verzoek en krijgt een antwoord dat het is aangenomen, met een Location-header die naar de aangemaakte opdracht wijst. Die header is absoluut vanaf de host: los hem op tegen de origin en niet tegen de basis-URL hierboven, anders vraag je een pad op dat niet bestaat.
2. 02Diezelfde opdracht staat ook in de body, maar dan verpakt in een veld command. De leesronde hieronder geeft hem kaal terug, zonder die verpakking: pak hem één keer uit en die eerste leesronde is meestal overbodig.
3. 03Je leest de opdracht tot zijn status definitief is: voltooid, mislukt, verlopen of geannuleerd. Alleen in behandeling is niet definitief, en een status die je niet kent telt óók als definitief, zodat een later toegevoegde waarde je nooit eeuwig laat doorlezen.
4. 04Een mislukte opdracht draagt de foutcode van de agent zelf, met zijn parameters, dezelfde die het paneel op je scherm rendert.

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

Elk endpoint zegt waarmee het antwoordt: 200 bij een leesactie, 201 als er iets is aangemaakt, 202 als je agent er nog werk aan heeft. En ze beschrijven allemaal de body die ze teruggeven, met een eigen naam per resource, zodat de code die je genereert één type per resource kent in plaats van één per endpoint.

Lijsten antwoorden met een pagina en een cursor; die cursor geef je terug tot hij leeg terugkomt. Een pagina bevat standaard 50 rijen en hoogstens 100.

Elk antwoord dat geen succes is heeft dezelfde vorm, wat er ook misging en waar het ook misging.

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

code

Het woord waarop je vertakt. Het komt uit een gesloten lijst, dus een waarde die je niet kent betekent dat je met een nieuwere versie praat dan die waartegen je gebouwd hebt.

message

Één Engelse zin, voor wie een log leest. Vertak er nooit op: de formulering mag veranderen.

detail

Een stabiele sleutel, waar die er is. Het is dezelfde sleutel die het paneel voor zijn eigen melding gebruikt, dus je kunt de zin in je eigen taal zetten.

params

De parameters die bij die sleutel horen: een limiet die overschreden werd, een naam die al bezet was, de host die weigerde.

requestId

Het kenmerk van dit verzoek, ook in een antwoordheader. Noem het als je ons ergens naar vraagt.

Je mag 120 verzoeken per minuut per sleutel doen, en 600 per account over al zijn sleutels samen. Die tweede grens bestaat zodat twintig sleutels niet twintig keer de belasting op dezelfde host leggen.

Alles wat iets aanmaakt accepteert een zelfgekozen idempotency-key-header. Herhaal hetzelfde verzoek met dezelfde waarde en je krijgt de eerste uitkomst terug, in plaats van een tweede machine, een tweede sleutel of een tweede opdracht.

Je mag ook je eigen x-request-id meesturen. Hij komt terug op het antwoord en verschijnt in onze logs, en dat is de goedkoopste manier om een regel van jouw kant naast een regel van de onze te leggen.

In de routering van deze API staat geen enkele providernaam. Welke systemen je kunt koppelen, welke velden hun inloggegevens hebben en wat ze kunnen, beantwoordt het discovery-endpoint; en de body waarmee je een integratie aanmaakt is uit datzelfde register gebouwd. Een provider die live gaat verschijnt in allebei zonder dat er één endpoint verandert.

Het werkt ook andersom. Vraag iets van een machine waarvan de provider dat niet kan – een console op een hostingaccount, een schijf op een gameserver – en je krijgt een weigering die de ontbrekende mogelijkheid bij naam noemt, voordat er iets naar je agent gaat.

Gegroepeerd zoals de specificatie ze groepeert. Elk pad komt achter de basis-URL, en ernaast staat de scope die het endpoint eist; staat er niets, dan volstaat een geldige sleutel.

Dezelfde informatie als een OpenAPI 3.1-document, gegenereerd uit de code die deze endpoints bedient in plaats van er los naast geschreven. Geef het aan een clientgenerator, een editor of een testsuite.

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

Binnen deze versie zijn wijzigingen toevoegingen: nieuwe endpoints, nieuwe optionele velden, nieuwe waarden in een lijst. Lees velden die je niet kent soepel, en behandel een foutcode die je niet kent niet als fataal.