Guida di riferimento alla REST API
Ogni widget Xcrud dialoga con un unico endpoint, core/ajax_crud.php - ecco la forma delle sue richieste/risposte.
Il parametro route
Ogni richiesta porta con sé un parametro query route che identifica quale configurazione di pagina usare - corrisponde al valore impostato dalla chiamata ->route() di quella pagina. L'API ririsolve server-side gli hook, le colonne e le regole di validazione della pagina a partire da quella rotta a ogni singola richiesta; non si fida mai di una copia fornita dal client.
Operazioni
| Operazione | Metodo HTTP | Note |
|---|---|---|
| Lista | GET | Restituisce {success, data, meta} - righe paginate più meta.page/meta.limit/meta.total/meta.sums. |
| Creazione | POST | Corpo JSON con i valori dei campi. Esegue in ordine before_insert()/validazione/insert/after_insert(). |
| Aggiornamento | PUT | Corpo JSON con i valori dei campi, indirizzato tramite la chiave primaria della riga. Esegue before_update()/validazione/update/after_update(). |
| Eliminazione | DELETE | Accetta un singolo id o un elenco bulk ?ids=. |
| Esportazione | GET | ?export=csv, ?export=xlsx, o ?export=pdf - trasmette in streaming l'insieme di risultati filtrato/ordinato corrente come file scaricabile, limitato a XcrudConfig::$exportRowLimit righe. |
| Importazione | POST | ?import=csv con un upload di file multipart. Ogni riga passa attraverso la stessa pipeline before_insert()/validazione/insert/after_insert() di una creazione a riga singola, limitata a XcrudConfig::$importRowLimit righe. |
Forma della risposta di lista
{
"success": true,
"data": [
{ "customerNumber": 103, "customerName": "Atelier graphique", "..." : "..." }
],
"meta": {
"page": 1,
"limit": 10,
"total": 122,
"sums": null
}
}meta.sums viene valorizzato invece di null quando una pagina chiama ->sum() o usa ->group_sum_columns() - vedi Righe raggruppate, somme e report.
Ogni scrittura è validata server-side
Un client che chiama ajax_crud.php direttamente - bypassando del tutto il JS del widget - non può raggiungere nulla che il normale caricamento di una pagina non potrebbe già raggiungere. Le richieste di creazione/aggiornamento sono validate rispetto esattamente alle stesse regole dichiarate nella configurazione PHP per quella rotta: XcrudConfig::$blacklistedTables/$blacklistedColumns regolano quali tabelle/colonne esistono affatto, e le regole ->validation_required()/->validation_pattern() di ogni campo vengono riverificate sul server, senza mai fidarsi del browser. Una colonna in blacklist non viene mai accettata in inserimento/aggiornamento indipendentemente da cosa contenga il corpo della richiesta, e un nome di colonna non riconosciuto viene silenziosamente ignorato invece di essere scritto. Vedi Sicurezza: blacklist di tabelle e colonne per il modello completo.