API-ul REST

Fiecare cale de pe această pagină se află în spatele URL-ului de bază de mai jos, iar fiecare cerere vă poartă cheia într-un antet Authorization. Nu există altă cale de intrare: niciun cookie de sesiune, nicio autentificare de tip basic, nicio cheie în șirul de interogare.

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

Creați o cheie în propriul dumneavoastră profil, la secțiunea Chei API. Ea vă aparține și aparține unui singur cont: nu este partajată cu colegii dumneavoastră și încetează să funcționeze în momentul în care părăsiți acel cont.

• O cheie expiră după 90 de zile, dacă nu alegeți altfel. Puteți alege un termen mai scurt sau niciunul; o cheie fără dată de expirare este o cheie pe care trebuie să vă amintiți să o revocați dumneavoastră.
• Rotația înseamnă să creați o cheie nouă și să o revocați pe cea veche, cu un moment la mijloc în care funcționează amândouă. Nu există rotație pe loc, pentru că aceasta v-ar lăsa fără o cheie funcțională dacă ceva merge prost la jumătatea drumului.
• Puteți lega o cheie de o listă de adrese. O cerere venită din altă parte este refuzată înainte să se citească ceva, iar acel refuz nu îi spune apelantului nimic despre cheie.
• Un membru deține cel mult 25 de chei. O cheie revocată își păstrează rândul, așa că puteți vedea și după aceea ce avea voie să facă atâta timp cât a existat.

O cheie poartă permisiuni: citire sau scriere, pentru fiecare parte a panoului. Ce poate face în realitate este intersecția dintre permisiunile cheii și permisiunile membrului căruia îi aparține.

Permisiunile sunt citite în timp real, la fiecare cerere. Retrageți-i ceva unui membru și fiecare cheie a acelui membru devine imediat mai restrânsă, fără ca cineva să fie nevoit să revoce ceva. Din acest motiv o cheie supraviețuiește unei schimbări de rol, în loc să fie invalidată de ea.

Infrastructura dumneavoastră este accesibilă doar prin agentul din propria dumneavoastră rețea, iar acel agent se conectează spre exterior. Așadar, un endpoint care modifică o mașină nu poate răspunde cu rezultatul: răspunde că a preluat comanda și vă dă ceva de urmărit.

1. 01Trimiteți cererea și primiți un răspuns de acceptare, cu un antet Location care indică spre comanda creată. Acel antet este absolut de la gazdă: rezolvați-l față de origine, nu față de adresa de bază de mai sus, altfel cereți o cale care nu există.
2. 02Aceeași comandă se află și în corpul răspunsului, dar împachetată într-un câmp command. Citirea de mai jos o returnează goală, fără acel ambalaj: despachetați-o o dată și prima citire devine de obicei inutilă.
3. 03Citiți comanda până când starea ei este finală: finalizată, eșuată, expirată sau anulată. Doar în așteptare nu este finală, iar o stare pe care nu o cunoașteți contează tot ca finală, astfel încât o valoare adăugată mai târziu să nu vă lase niciodată să citiți la nesfârșit.
4. 04O comandă eșuată poartă chiar codul de eroare al agentului, împreună cu argumentele lui, aceleași pe care panoul le afișează pe ecranul dumneavoastră.

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

Fiecare punct de acces spune cu ce răspunde: 200 la o citire, 201 când s-a creat ceva, 202 când agentul mai are de lucru. Și toate descriu corpul pe care îl returnează, cu un nume propriu pentru fiecare resursă, astfel încât codul generat are un tip pentru fiecare resursă, nu unul pentru fiecare punct de acces.

Listele răspund cu o pagină și un cursor; transmiteți acel cursor înapoi până când iese gol. În mod implicit, o pagină conține 50 de rânduri, iar limita maximă este de 100 de rânduri.

Orice răspuns care nu este un succes are aceeași formă, indiferent ce a mers prost și unde.

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

code

Cuvântul după care vă ramificați. Provine dintr-o listă închisă, așa că o valoare pe care nu o cunoașteți înseamnă că vorbiți cu o versiune mai nouă decât cea pentru care ați construit.

message

O singură propoziție în engleză, pentru cine citește un jurnal. Nu vă ramificați niciodată după ea: formularea se poate schimba oricând.

detail

O cheie stabilă, acolo unde există una. Este aceeași cheie pe care o folosește panoul pentru propriul mesaj, așa că puteți formula propoziția în limba dumneavoastră.

params

Argumentele care aparțin acelei chei: o limită depășită, un nume deja ocupat, gazda care a refuzat.

requestId

Identificatorul acestei cereri, prezent și într-un antet de răspuns. Citați-l când ne întrebați ceva.

Puteți face 120 de cereri pe minut pentru fiecare cheie și 600 de cereri pentru fiecare cont, însumând toate cheile lui. A doua limită există pentru ca douăzeci de chei să nu poată pune de douăzeci de ori mai multă sarcină pe aceeași gazdă.

Tot ce creează ceva acceptă un antet idempotency-key compus de dumneavoastră. Repetați aceeași cerere cu aceeași valoare și primiți înapoi primul rezultat, în loc de a doua mașină, a doua cheie sau a doua comandă.

Puteți trimite și propriul dumneavoastră x-request-id. Vine înapoi în răspuns și apare în jurnalele noastre, ceea ce este cel mai ieftin mod de a pune o linie de la dumneavoastră lângă una de la noi.

În rutarea acestui API nu apare niciun nume de furnizor. Ce sisteme puteți conecta, ce câmpuri cer datele lor de autentificare și ce pot face spune endpointul de descoperire, iar corpul pe care îl trimiteți pentru a crea o integrare este construit din același registru. Un furnizor care intră în funcțiune apare în amândouă fără să se schimbe vreun endpoint.

Funcționează și invers. Cereți ceva de la o mașină al cărei furnizor nu poate face acel lucru (o consolă pe un cont de găzduire, un disc pe un server de jocuri) și primiți un refuz care numește capabilitatea lipsă, înainte să se trimită ceva agentului dumneavoastră.

Grupate așa cum le grupează specificația. Fiecare cale vine după URL-ul de bază, iar lângă ea stă permisiunea cerută de endpoint; unde nu stă nimic, este suficientă o cheie validă.

Aceleași informații sub forma unui document OpenAPI 3.1, generat din codul care servește aceste endpointuri, nu scris pe lângă el. Dați-l unui generator de clienți, unui editor sau unei suite de teste.

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

În cadrul acestei versiuni, modificările sunt adăugiri: endpointuri noi, câmpuri opționale noi, valori noi într-o listă. Citiți îngăduitor câmpurile pe care nu le cunoașteți și nu tratați drept fatal un cod de eroare pe care nu îl cunoașteți.