API

Bobuild ti permette di esporre i tuoi dati tramite una REST API. È una funzionalità potente in molti scenari:

• vuoi rendere i tuoi dati disponibili a un sito di terze parti o a un'app mobile
• vuoi costruire uno script che recupera dati dalla tua app e li invia a un sistema di terze parti
• vuoi costruire uno script che recupera dati da un sistema di terze parti e li invia alla tua app
• vuoi costruire uno script che recupera dati dalla tua app, li elabora e li ricarica

Con questa funzionalità puoi costruire la tua API senza scrivere codice. Definisci gli endpoint che ti servono, i campi da esporre e il metodo di autenticazione. Bobuild ti offre un modo potente per creare quante integrazioni servono a te e ai tuoi utenti, anche con viste diverse dello stesso dato secondo i ruoli. Per embed, iPaaS e pattern mobile intorno all'API, vedi Integrazioni.

suggerimento

Contattaci per abilitarla per la tua app.

Definire gli endpoint

Creare un'API per la tua app significa definire uno o più endpoint. Un endpoint è l'URL che un client esterno chiamerà, sempre a partire da https://YOURDOMAIN/_api seguito da un percorso arbitrario che decidi tu. Così puoi progettare lo schema di naming in modo molto flessibile.

Per ogni endpoint puoi scegliere uno dei seguenti comportamenti:

Tipo endpoint	Metodo HTTP	Parametro numerico	Descrizione
List	GET	Opzionale	Restituisce un elenco di record che corrispondono a un criterio
Aggregate	GET	Opzionale	Restituisce totali raggruppati (stesso motore di pivot / chart)
Create	POST	Opzionale	Accetta dati dal client e crea uno o più record
Modify	PATCH	Obbligatorio	Accetta dati dal client e modifica un record
Delete	DELETE	Obbligatorio	Elimina un record

Gli endpoint con parametro numerico avranno la forma https://YOURDOMAIN/_api/ENDPOINT/1. Il parametro numerico può essere usato liberamente nel filtro dell'endpoint per definire una logica di autorizzazione.

Esempio

Supponiamo che tu voglia esporre un catalogo di brani e accettare invii di recensioni. Creerai i seguenti endpoint:

URL	Metodo HTTP	Tipo	Descrizione
https://myapp.bobuild.com/_api/songs	GET	List	Restituisce tutti i brani
https://myapp.bobuild.com/_api/song-review/34	POST	Create	Crea una nuova recensione per il brano con ID 34

List

Gli endpoint List restituiscono un oggetto JSON con un elenco di record che corrispondono a un criterio. Sono concettualmente molto simili a un grid widget perché restituiscono dati tabulari. Per un endpoint List dovrai configurare:

• i criteri di filtro per selezionare i record da restituire
• l'elenco dei campi da restituire per ogni record
• i criteri di ordinamento per restituire i record

I record vengono restituiti a pagine. Se il filtro corrisponde a più di 100 record, verranno restituiti solo i primi 100. Tuttavia, verrà restituita una proprietà total che segnala che ci sono altri record da recuperare. A quel punto, il client può richiamare di nuovo l'endpoint API passando il parametro ?page=2 e così via finché gli elementi recuperati corrispondono alla proprietà total.

Le risposte List includono anche header HTTP Link con rel="next" e rel="prev" quando applicabile, e gli stessi URL in un membro JSON _links ({ "next": { "href": "…" }, "prev": { "href": "…" } }) quando quelle relazioni esistono. Preferisci quegli URL piuttosto che costruire a mano i numeri di pagina. Quando l'endpoint restituisce l'id del record e ordina per id, il link next usa un filtro keyset stabile (?id:gt=… o ?id:lt=… a seconda della direzione di ordinamento) così inserimenti o cancellazioni tra una richiesta e l'altra non saltano né duplicano righe; altrimenti next resta basato su pagina (?page=).

Se un parametro di query List non è valido (ad esempio un page non numerico, o un valore di filtro non valido per quel tipo di campo), l'endpoint risponde con HTTP 400 e { "success": false, "error": "Invalid request parameters" } invece di trattare il valore errato come un risultato vuoto.

Esempio

Una chiamata GET a https://myapp.bobuild.com/_api/songs restituirà:

{
    "page": 1,
    "total": 305,
    "items": [
        {
            "id": 1,
            "title": "Song nr. 1",
            "year": 1985
        },
        {
            "id": 2,
            "title": "Song nr. 2",
            "year": 1999
        },
        ...
    ],
    "_links": {
        "next": { "href": "https://myapp.bobuild.com/_api/songs?page=2" }
    }
}

Conterrà solo i primi 100 elementi. Segui _links.next.href (o l'header Link) finché non c'è un link next, oppure finché gli elementi recuperati corrispondono al numero nella proprietà total.

Nota che i tuoi client possono fornire parametri di filtro personalizzati. Tali parametri verranno applicati sopra il filtro che hai definito per l'endpoint, quindi avranno solo l'effetto di restringere ulteriormente l'insieme di record restituiti. Esempi: https://myapp.bobuild.com/_api/songs?year=1999 per ottenere solo i record il cui year.

Esempio

Esempi di chiamate API con filtri personalizzati:

• https://myapp.bobuild.com/_api/songs?year=1999 (tutti i brani con year = 1999)
• https://myapp.bobuild.com/_api/songs?year:gt=1998 (tutti i brani con year > 1998)

Aggregate

Gli endpoint Aggregate restituiscono totali pre-raggruppati — la controparte API di un pivot o chart, non un oggetto JSON per record. Preferiscili da Custom View e Custom JS (auth di sessione) invece di scaricare un List completo e aggregare nel browser.

Configura:

• Object e filter di base (sempre applicato)
• Dimensions — raggruppamenti (variable diventa la chiave di risposta, field, axis row o column, direzione di ordinamento, formati data/ora opzionali). Al massimo cinque dimensioni per asse.
• Measures — aggregazioni (variable, op e field quando serve). Op: count, count_distinct, sum, avg, min, max, text. Al massimo dieci misure; il default è un semplice count.
• Opzionali sort measure e limit (top-N valori distinti della dimensione primaria di riga dopo l'ordinamento)
• Opzionali mapping di filtri in query string (stessa idea dei filtri List)
• Max items — tetto alle combinazioni di gruppo (HTTP 400 se superato)

Forma della risposta (celle piatte — i client le rimodellano per i chart):

{
  "items": [
    {
      "dimensions": { "region": "North", "product": "Widget" },
      "measures": { "count": 12, "revenue": 4500 }
    }
  ],
  "total": 1,
  "meta": {
    "dimensions": [
      { "variable": "region", "field": "region", "axis": "row", "dir": "asc" },
      { "variable": "product", "field": "product.name", "axis": "column", "dir": "asc" }
    ],
    "measures": [
      { "variable": "count", "op": "count" },
      { "variable": "revenue", "op": "sum", "field": "amount" }
    ]
  }
}

Create

Gli endpoint Create possono creare uno o più record con una singola chiamata. Puoi pensarli come la controparte API di un form widget. I client devono inviare un payload JSON che rappresenta i campi del record da creare.

Quando configuri un endpoint Create definirai quali campi saranno accettati dal client e quali saranno obbligatori. Ricorda che gli ID vengono sempre assegnati automaticamente da Bobuild, quindi i client non potranno fornire l'ID del record da creare.

Esempio

Ecco il payload che un client potrebbe inviare con una richiesta POST a https://myapp.bobuild.com/_api/song-review/34:

{
  "rating": 4.5,
  "comment": "Feels good"
}

Per creare più record con una singola chiamata, può essere inviato un array. Vediamo come creare più brani con una richiesta. Il client invierà una richiesta POST a https://myapp.bobuild.com/_api/add-songs con il seguente payload:

[
  {
    "title": "Song nr. 1",
    "year": 1985
  },
  {
    "title": "Song nr. 2",
    "year": 1999
  }
]

Se la creazione ha successo, verrà restituita una risposta positiva con l'ID del record appena creato:

{
  "success": true,
  "object": "song_review",
  "id": 675
}

Se hai creato più record, la risposta avrà questa forma:

{
  "success": true,
  "object": "song_review",
  "id": [675, 676, 677]
}

Se il client fornisce un payload non valido, verrà restituito un messaggio di errore:

{
  "success": false,
  "error": "Invalid data for field: cover"
}

Analogamente a un form widget, a un endpoint Create possono essere collegate una o più Task che verranno eseguite dopo la creazione del record. Vedi Validazione input per i campi obbligatori e i controlli consapevoli del database.

Modify

Analogamente agli endpoint Create, gli endpoint Modify sono la controparte API di un form widget. Servono a modificare un singolo record. I client non devono inviare l'intero record ma possono fornire solo il sottoinsieme dei campi che vogliono modificare.

Quando configuri un endpoint Modify, definisci quali campi possono essere modificati.

Esempio

Ecco il payload che un client potrebbe inviare con una richiesta PATCH a https://myapp.bobuild.com/_api/modify-song/34:

{
  "year": 2001
}

Se la modifica ha avuto successo, verrà restituita una risposta positiva:

{
  "success": true
}

Se il client fornisce un payload non valido, verrà restituito un messaggio di errore:

{
  "success": false,
  "error": "Invalid data for field: year"
}

Analogamente a un form widget, a un endpoint Modify possono essere collegate una o più Task che verranno eseguite dopo l'aggiornamento del record. Vedi Validazione input.

Delete

Un endpoint Delete prende semplicemente l'ID di un record da eliminare e risponde al client. Puoi configurare un criterio di filtro per decidere se il record può essere eliminato o no.

Se l'eliminazione ha avuto successo, verrà restituita una risposta positiva:

{
  "success": true
}

Altrimenti, verrà restituito un messaggio di errore:

{
  "success": false,
  "error": "Record not found"
}

A un endpoint Delete possono essere collegate una o più Task che verranno eseguite dopo l'eliminazione del record.

Se vuoi esporre un endpoint API che esegue più eliminazioni in una volta (anche su oggetti diversi) o vuoi un controllo più fine sull'esecuzione delle Task prima/dopo l'eliminazione, è consigliabile usare invece un endpoint Modify con una o più Task di eliminazione collegate.

Validazione input

Gli endpoint Create e Modify dovrebbero rifiutare payload errati come un form ben costruito — prima che dati errati si diffondano ad altri sistemi. Bobuild combina regole sui campi con controlli opzionali via Task.

Scenari tipici:

• un'app mobile deve inviare un titolo obbligatorio e una valutazione nel range;
• un'integrazione non deve creare prenotazioni sovrapposte;
• tipi JSON di campo non validi devono fallire con un 400 chiaro invece di salvataggi parziali.

Controlli su campi e tipi

Nella scheda Fields dell'endpoint scegli quali campi il client può inviare. Per gli endpoint Create segni anche quali di quei campi sono required.

Bobuild applica comunque i vincoli del campo sull'oggetto (ad esempio min / max sui numeri, limiti di lunghezza e controlli di tipo). Dati non validi o mancanti restituiscono:

{
  "success": false,
  "error": "Invalid data for field: year"
}

(o un messaggio simile che indica il campo in errore). Correggi il payload e riprova — nulla viene committato quando la validazione fallisce in questa fase.

Validazione consapevole del database con Task

Le regole sui campi non possono esprimere "questa riga non deve essere in conflitto con altre righe già memorizzate". Per quello, collega una Task Raise a validation error all'endpoint Create o Modify (stessa azione dei form).

Il record viene scritto e le Task vengono eseguite in una transazione. Se l'azione scatta:

1. le azioni Task rimanenti si fermano
2. la transazione viene annullata
3. l'API risponde con HTTP 400 e:

{
  "success": false,
  "error": "Your custom message here"
}

Usa le Conditions della Task (spesso con campi automatici che contano i conflitti) e imposta l'Error message restituito al client.

Autenticazione

Ogni endpoint sceglie come i chiamanti dimostrano chi sono. Scegli il metodo adatto al client: gli script server-to-server dovrebbero usare API key; JavaScript in esecuzione nelle tue pagine Bobuild può riusare la sessione browser autenticata così non incorpori mai segreti nel codice front-end.

API Key

Crea le chiavi in Settings → API → API Keys (Add API Key). Ottieni una descrizione e un segreto mostrato una volta nella finestra API Key Created — conservalo come una password.

Nella scheda Authentication dell'endpoint, scegli API Key e spunta quali chiavi sono consentite.

Chiama con un bearer token:

curl --header "Authorization: Bearer YOUR_API_KEY" https://myapp.bobuild.com/_api/songs

Browser Session

Scegli Browser Session quando il chiamante è il browser dell'utente sulla tua app (ad esempio fetch da Custom JS o una Custom View). Seleziona l'User object che deve essere autenticato.

L'endpoint è raggiungibile solo dai browser in cui un utente autenticato come quell'oggetto è già loggato su una pagina qualsiasi dell'app. Esempio:

fetch('https://myapp.bobuild.com/_api/songs', {
  credentials: 'include'
})
  .then(function (r) { return r.json(); })
  .then(console.log);

credentials: 'include' è obbligatorio così viene inviato il cookie di sessione. Nessuna API key compare nel sorgente pagina — migliore sicurezza per portali interattivi — mentre le integrazioni server continuano a usare API key.

suggerimento

Usa Browser Session per UI first-party. Usa API key per backend, cron job e sistemi esterni.

IP di origine consentiti

Su ogni endpoint puoi limitare i chiamanti per IP del client, indipendentemente dal metodo di autenticazione. Casi tipici:

• un'integrazione partner che deve partire solo dai loro uffici o dagli indirizzi di uscita cloud;
• un job di sync interno che non deve essere raggiungibile da Internet anche se una chiave viene esposta;
• restringere un endpoint Modify/Delete a un host middleware noto.

Nelle impostazioni dell'endpoint, sotto Allowed source IPs, aggiungi uno o più indirizzi o subnet CIDR (IPv4 o IPv6), ad esempio 203.0.113.10 o 10.0.0.0/8. Lascia l'elenco vuoto per accettare connessioni da qualsiasi IP (l'autenticazione continua ad applicarsi).

Quando l'elenco non è vuoto e l'indirizzo del chiamante non è compreso, Bobuild risponde con HTTP 403 Forbidden e non esegue l'endpoint. Il controllo usa l'indirizzo remoto visto dal server dell'app.

File e immagini

Mentre i tipi base come testo, numeri e booleani vengono restituiti come valori JSON semplici, i tipi complessi come file e immagini sono rappresentati in modo speciale.

Quando chiami un endpoint List per leggere dati da Bobuild, verranno restituiti come URL del file effettivo:

{
    "page": 1,
    "total": 1,
    "items": [
        {
            "id": 1,
            "title": "Song nr. 1",
            "cover": "https://xxxxxxxxxxxxxxxx/song_1_cover.jpg"
        }
    ]
}

Quando chiami un endpoint Create o Modify per inviare dati a Bobuild, devi inviare i dati binari come stringa codificata in base64 insieme al nome file:

{
  "title": "Song nr. 1",
  "cover": {
    "data": "<base64-encoded binary data>",
    "name": "song_1_cover.jpg"
  }
}

Librerie client

In genere non ti serve una libreria speciale per accedere a un'API creata su Bobuild perché basta eseguire chiamate HTTP con payload JSON. Possiamo però fornire librerie di utilità per linguaggi di programmazione popolari che incapsulano queste chiamate e aiutano a gestire cose come la paginazione con facilità. Contattaci!

Documentazione OpenAPI

In Settings → API → OpenAPI puoi creare documenti OpenAPI curati per gli integratori — scarica uno spec JSON, oppure pubblicalo a un URL pubblico che strumenti come ReDoc possono caricare.

Usi tipici:

• consegnare ai partner un contratto machine-readable degli endpoint che possono chiamare;
• tenere allineati Postman / generatori di codice senza scrivere lo spec a mano;
• pubblicare un riferimento navigabile per un'API di catalogo pubblica.

Crea un documento

1. Apri Settings → API e la scheda OpenAPI.
2. Add OpenAPI Document — imposta Title, Version opzionale (predefinita 1.0.0) e Description.
3. Spunta quali endpoint includere (puoi mescolare List / Create / Modify / Delete).
4. Salva, poi Download il JSON generato quando gli endpoint cambiano (il file è generato al download dalle definizioni correnti).

Il titolo è anche usato come radice del nome file di download e come OpenAPI info.title.

Pubblica a un URL pubblico

Nella finestra del documento, abilita Expose this document at a public HTTP endpoint (no API key required). Bobuild lo serve su:

https://YOURDOMAIN/_api/_openapi/<slug>.json

Lo slug deriva dal titolo (minuscolo, i caratteri non-word diventano _). I documenti non esposti non sono raggiungibili via HTTPS. Gli spec pubblicati inviano CORS Access-Control-Allow-Origin: * così i viewer basati su browser (ad esempio ReDoc) possono caricarli da un'altra origine. Il Builder mostra l'URL e una scorciatoia per aprirlo in ReDoc.

Pubblicare la documentazione non bypassa l'autenticazione degli endpoint — i chiamanti hanno comunque bisogno di API key o sessione browser come configurato su ciascun endpoint. Gli IP di origine consentiti continuano ad applicarsi a quelle chiamate.

La documentazione generata descrive auth, paging, filtri, create, allowlist IP e — quando rilevante — come i campi file e immagine appaiono come URL firmati temporanei.

Roadmap funzionalità

• Rilascio delle librerie client su GitHub.