Riferimento dell’API REST

Da dove viene questa pagina

Questo riferimento non è scritto, è letto. Ogni rotta, ogni metodo e ogni ambito qui sotto vengono dal contratto OpenAPI compilato dentro il binario dell’API, e un controllo confronta quel contratto con il codice in esecuzione a ogni build.

Un riferimento tenuto a mano comincia a divergere la settimana dopo essere stato scritto, e da quel momento è peggio di nessun riferimento, perché lo si crede. L’unico modo per non divergere è non avere una seconda copia da cui divergere.

Qui sono elencate le operazioni che una chiave API può chiamare, e nessuna altra. Il resto del servizio la dashboard lo guida con rotte che raggiunge solo una sessione dal browser: non fanno parte dell’API pubblica, cambiano senza preavviso, e documentarle le trasformerebbe in una promessa che nessuno ha fatto.

Qui trovi la superficie: dove sta una rotta e a che cosa serve. Il resto lo porta il contratto — schemi di richiesta e risposta, codici di errore, limiti di frequenza — ed è il documento da leggere quando una chiamata risponde qualcosa che non ti aspettavi. La copia che puoi scaricare contiene le stesse operazioni di questa pagina, e solo quelle.

Autenticazione

Tre modi di dimostrare chi sei, e non sono intercambiabili. La chiave con ambiti è quella pensata per i programmi; la sessione è quella che il browser tiene mentre usi la dashboard.

Gli ambiti di scrittura non comprendono quelli di lettura. Altrimenti chi guarda una chiave leggerebbe jobs:write e dovrebbe ricordarsi che copre anche la lettura.

Le operazioni che non accettano nessuna chiave — emettere credenziali, impegnare un pagamento, distruggere un account — mancano da questa pagina esattamente per questo. È una decisione e non una dimenticanza: una chiave capace di crearne un’altra renderebbe inutile revocare la prima.

Operazioni

Raggruppate come le raggruppa il contratto. Un pezzo di percorso fra parentesi graffe è un parametro da sostituire; la colonna dell’ambito dice che cosa deve portare una chiave perché quella chiamata passi.