Vai al contenuto
Verificata

Panoramica

Un solo endpoint, un solo formato di risposta e i 337 metodi che una chiave API può raggiungere.

Ogni schermata della dashboard di Xuda, ogni programma Studio e ogni integrazione di terze parti chiama la stessa superficie HTTP: CPI, abbreviazione del dispatcher dei metodi della piattaforma. C'è una sola forma di endpoint, /cpi/<method>, e un solo formato di risposta. Impararlo una volta copre tutti i 337 metodi che una chiave API dell'account può raggiungere oggi.

L'endpoint

POST https://xuda.ai/cpi/<method>GET  https://xuda.ai/cpi/<method>

<method> è il nome di un metodo come get_account_projects o dbs_read, mai un percorso di risorsa con un id dentro. Ogni input, compreso un id, è un parametro: con POST è un campo nel corpo JSON, con GET è un parametro della query string (vedi Chiamare un metodo per le regole su corpo e query e per gli esempi pratici in cURL, JavaScript e Python).

Questo sito di documentazione

La documentazione è servita su xuda.ai/docs, quindi la sandbox di questo sito chiama /cpi/<method> sulla stessa origine. Il tuo codice, in esecuzione ovunque, chiama direttamente https://xuda.ai/cpi/<method>.

Il formato di risposta

Ogni metodo, in caso di successo o di errore, risponde con la stessa forma:

json
{ "code": 1, "data": { "...": "..." } }
  • code > 0 indica successo. Il numero in sé non ha altro significato oltre a essere positivo, leggi data.
  • code < 0 indica un errore. data è di solito una stringa di messaggio; un errore di validazione aggiunge anche un campo message derivato da essa. Vedi Errori per i codici su cui vale la pena ramificare e quelli da registrare e mostrare e basta.
  • Un metodo che restituisce un file o un tipo di contenuto personalizzato (un export CSV, un'immagine) salta il formato JSON e imposta invece i propri header e il proprio corpo. È l'eccezione, non la regola.
  • Una risposta riuscita contiene un header xu-region che indica la regione Xuda che ha gestito la chiamata. Una risposta di errore non lo contiene.

Clearance e il muro privato

Ogni metodo ha una clearance: public, user, user_access, developer o admin. Indica chi può raggiungerlo tramite una sessione dashboard autenticata: un metodo public non richiede nulla, gli altri richiedono una sessione di quel livello o superiore.

Una chiave API è un muro separato, non un'altra clearance. Un metodo ha anche un flag private. private: true è assoluto: nessuna chiave API può chiamarlo, nemmeno una con accesso completo, a prescindere dalla sua clearance. Circa un quarto del catalogo è pubblico in questo senso: 337 metodi in 24 microservizi, che spaziano da Voice e Domains a Drive e all'API di authoring di Studio. Gli altri, compresi tutti i metodi di api_module stesso (i metodi che creano e gestiscono le chiavi API), restano riservati alle sessioni. Autenticazione tratta l'accesso completo e quello personalizzato delle chiavi, e ogni guida di modulo qui sotto termina con la tabella aggiornata di ciò che il suo microservizio espone.

Trovare un metodo

Il riferimento API interattivo elenca tutti i 337 metodi con i loro campi e ti permette di eseguirne uno sul tuo account direttamente dal browser.