API pubblica
API pubblica di Blueputto per l'accesso CRUD autenticato ai record dell'area di lavoro, con endpoint versionati, chiavi API, paginazione, filtri e azioni di flusso di lavoro.
Grzegorz
L'API pubblica è il livello di integrazione autenticato di Blueputto. Espone gli stessi record principali con cui l'applicazione lavora ogni giorno, consentendo ai sistemi esterni di creare, leggere, aggiornare e rimuovere dati operativi senza introdurre un secondo modello di contenuto accanto all'interfaccia utente.
Questa API si trova sotto /v1 ed è progettata per funzionare con le API Keys a livello di organizzazione. Questo la rende la funzionalità che i team usano quando i dati di Blueputto devono confluire in un sito web, un'automazione, uno script di importazione, una dashboard interna o un altro sistema di prodotto.
Un'unica API versionata per le principali risorse dell'area di lavoro
Il punto di ingresso su /v1 restituisce un payload di individuazione compatto con la versione dell'API, il formato di autenticazione, l'URL del documento OpenAPI e l'elenco delle risorse attualmente esposte.
Nell'implementazione attuale, la superficie pubblica copre:
documenti,
elementi,
raccolte,
cartelle,
categorie,
stati,
etichette,
e modelli di documento.
La maggior parte di queste risorse supporta il percorso operativo standard di elenco, recupero, creazione, aggiornamento ed eliminazione. L'API espone anche azioni specifiche del flusso di lavoro dove l'interfaccia utente ne ha bisogno, come:
ripristino ed eliminazione permanente per documenti ed elementi,
duplicazione per i documenti,
riordinamento per categorie, stati ed etichette,
e filtro solo attivi per i modelli di documento.
Questo è ciò che rende l'API pubblica più di un livello di esportazione in sola lettura. Mappa da vicino il ciclo di vita reale dei record già visibile in Blueputto stesso.
Autenticazione e struttura della risposta restano prevedibili
L'API pubblica accetta la credenziale dell'organizzazione in una delle due forme standard:
x-api-key,
oppure Authorization: Bearer <key>.
Questo offre ai team flessibilità quando collegano Blueputto a diversi runtime, gateway e stili di SDK. La chiave stessa viene creata all'interno dell'applicazione dalla pagina delle impostazioni API Keys.
Anche la struttura della risposta è intenzionalmente coerente. Le risposte di singola risorsa vengono restituite all'interno di un contenitore data. Gli endpoint di elenco restituiscono data insieme a meta, che include dettagli di paginazione come page, limit, total items, total pages e lo stato della pagina successiva o precedente.
Nell'attuale insieme di risorse, l'API espone anche filtri pratici che rispecchiano i flussi di lavoro reali dell'interfaccia utente, inclusi search, deletedOnly, folderId, withoutFolder e activeOnly.
Costruita attorno alle stesse regole operative dell'app
L'aspetto utile dell'API pubblica di Blueputto non è solo che i record sono raggiungibili esternamente. È che la superficie di integrazione segue le stesse regole che il prodotto applica già nell'interfaccia utente.
Ad esempio, l'eliminazione di documenti ed elementi è modellata come un flusso che passa prima dal cestino anziché dalla distruzione immediata. Alcune operazioni sui documenti possono restituire una risposta di stato bloccato quando il record non è attualmente modificabile. La limitazione della frequenza viene applicata per ogni chiave API, con il limite predefinito del backend attualmente impostato su 5 req/s per chiave.
Questo mantiene l'API allineata al comportamento reale dell'applicazione. Le integrazioni esterne lavorano con il modello di risorsa effettivo di Blueputto, non con un canale laterale semplificato che si comporta in modo diverso dal prodotto.
