L’API REST

Ogni percorso di questa pagina sta dietro l’URL di base qui sotto, e ogni richiesta porta la sua chiave in un’intestazione Authorization. Non esiste un’altra via d’accesso: nessun cookie di sessione, nessuna basic auth, nessuna chiave nella query string.

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

Una chiave si crea nella sua pagina di profilo, sotto Chiavi API. Appartiene a lei e a un solo account: non è condivisa con i suoi colleghi e smette di funzionare nel momento in cui lascia quell’account.

• Salvo diversa indicazione, una chiave scade dopo 90 giorni. Può scegliere un periodo più breve, oppure nessuna scadenza; una chiave senza data di fine è una chiave che nessuno revocherà al posto suo.
• Ruotare una chiave significa crearne una nuova e revocare quella vecchia, con un intervallo in cui funzionano entrambe. Non esiste una sostituzione diretta della chiave esistente, perché la lascerebbe senza una chiave funzionante se qualcosa andasse storto a metà strada.
• Può vincolare una chiave a un elenco di indirizzi. Una richiesta proveniente da qualsiasi altro punto viene rifiutata prima che venga letto alcunché, e quel rifiuto non rivela nulla sulla chiave a chi la effettua.
• Un membro può avere al massimo 25 chiavi. Una chiave revocata mantiene la sua riga, così anche in seguito si può vedere che cosa le era consentito fare quando era in uso.

Una chiave porta con sé degli ambiti: lettura o scrittura, per ogni parte del pannello. Ciò che può fare davvero è l’intersezione fra quegli ambiti e le autorizzazioni del membro a cui appartiene.

Le autorizzazioni vengono lette in tempo reale, a ogni richiesta. Se toglie qualcosa a un membro, tutte le chiavi di quel membro si restringono all’istante, senza che nessuno debba revocare alcunché. È anche per questo che una chiave sopravvive a un cambio di ruolo invece di essere invalidata da esso.

La sua infrastruttura è raggiungibile soltanto attraverso l’agente che si trova nella sua rete, e quell’agente si connette verso l’esterno. Perciò un endpoint che modifica una macchina non può rispondere con il risultato: risponde che l’ordine è stato accettato e le consegna qualcosa da seguire.

1. 01Invia la richiesta e riceve una risposta di accettazione, con un’intestazione Location che rimanda al comando appena creato. Quell’intestazione è assoluta a partire dall’host: va risolta rispetto all’origine e non rispetto all’URL di base qui sopra, altrimenti si finisce per chiedere un percorso che non esiste.
2. 02Quello stesso comando si trova anche nel corpo, ma avvolto in un campo command. La lettura qui sotto lo restituisce nudo, senza quell’involucro: basta scartarlo una volta e la prima lettura di solito è superflua.
3. 03Legge il comando finché il suo stato non è definitivo: completato, non riuscito, scaduto o annullato. Solo in attesa non è definitivo, e uno stato sconosciuto vale anch’esso come definitivo, così un valore aggiunto in seguito non lascia mai la lettura aperta all’infinito.
4. 04Un comando non riuscito porta con sé il codice di errore dell’agente stesso, con i suoi argomenti: gli stessi che il pannello mostra sul suo schermo.

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

Ogni endpoint dichiara con che cosa risponde: 200 per una lettura, 201 quando qualcosa è stato creato, 202 quando l’agente ha ancora del lavoro da svolgere. E tutti descrivono il corpo che restituiscono, con un nome proprio per risorsa, così il codice generato contiene un tipo per risorsa e non uno per endpoint.

Gli elenchi rispondono con una pagina e un cursore; quel cursore va restituito finché non torna vuoto. Per impostazione predefinita una pagina contiene 50 righe e al massimo 100.

Ogni risposta che non è un successo ha la stessa forma, qualunque cosa sia andata storta e in qualunque punto sia successo.

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

code

La parola su cui ramificare. Proviene da un elenco chiuso, quindi un valore che non conosce significa che sta parlando con una versione più recente di quella per cui ha sviluppato.

message

Una frase in inglese, per chi legge un log. Non ci ramifichi mai sopra: la formulazione può cambiare in qualsiasi momento.

detail

Una chiave stabile, quando esiste. È la stessa chiave che il pannello usa per il proprio messaggio, così può rendere la frase nella sua lingua.

params

Gli argomenti che appartengono a quella chiave: un limite superato, un nome già occupato, l’host che ha rifiutato.

requestId

L’identificativo di questa richiesta, presente anche in un’intestazione della risposta. Lo citi quando ci chiede qualcosa.

Può effettuare 120 richieste al minuto per chiave e 600 per account su tutte le sue chiavi. Il secondo limite esiste perché venti chiavi non possano mettere venti volte il carico sullo stesso host.

Tutto ciò che crea qualcosa accetta un’intestazione idempotency-key scelta da lei. Ripeta la stessa richiesta con lo stesso valore e riceverà indietro il primo esito, invece di una seconda macchina, di una seconda chiave o di un secondo comando.

Può anche inviare un suo x-request-id. Torna sulla risposta e compare nei nostri log: è il modo più economico per affiancare una riga dalla sua parte a una riga dalla nostra.

Nel routing di questa API non compare il nome di un solo provider. Quali sistemi si possono collegare, di quali campi si compongono le loro credenziali e di che cosa sono capaci è ciò a cui risponde l’endpoint di discovery, e il corpo che invia per creare un’integrazione è costruito a partire dallo stesso registro. Un provider che entra in funzione compare in entrambi senza che cambi un solo endpoint.

Vale anche il contrario. Se chiede a una macchina qualcosa che il suo provider non sa fare (una console su un account di hosting, un disco su un server di gioco), riceve un rifiuto che indica per nome la funzionalità mancante. Il rifiuto arriva prima che qualsiasi cosa venga inviata al suo agente.

Raggruppati come li raggruppa la specifica. Ogni percorso va dopo l’URL di base e accanto a esso è indicato l’ambito richiesto dall’endpoint; dove non c’è nulla, basta una chiave valida.

Le stesse informazioni sotto forma di documento OpenAPI 3.1, generato dal codice che serve questi endpoint invece di essere scritto a parte. Lo passi a un generatore di client, a un editor o a una suite di test.

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

All’interno di questa versione i cambiamenti sono aggiunte: nuovi endpoint, nuovi campi facoltativi, nuovi valori in un elenco. Legga con tolleranza i campi che non conosce e non tratti come fatale un codice di errore che non conosce.