Che cos’è Data API builder
Data API builder (DAB) è uno strumento open source di Microsoft che genera automaticamente endpoint REST e GraphQL sicuri sopra un database relazionale (Azure SQL, SQL Server, SQL database in Fabric, oltre a Cosmos DB, PostgreSQL e MySQL). Invece di scrivere e mantenere un backend custom, si descrive in un file di configurazione JSON quali oggetti del database esporre — tabelle, view e stored procedure — e DAB si occupa di routing, serializzazione, paginazione e controllo degli accessi. Il tool si avvia come servizio, tipicamente in container (ad esempio su Azure Container Apps), e legge la configurazione all’avvio.
Il criterio di scelta da ricordare: DAB conviene quando serve esporre rapidamente dati esistenti come API standard senza logica applicativa complessa. Se servono workflow, orchestrazioni o regole di business articolate, un’API custom resta più adatta.
Endpoint REST e GraphQL dalla stessa configurazione
Ogni oggetto esposto è un’entity. Dalla stessa definizione DAB genera contemporaneamente:
- un endpoint REST per entity, con filtri, ordinamento e paginazione tramite query string;
- un unico endpoint GraphQL con query e mutation, capace di seguire le relazioni fra entity in una sola richiesta.
I due protocolli si abilitano in modo indipendente: un’entity può essere esposta solo in GraphQL, solo in REST o entrambi.
Punti d’attenzione tipici:
- le view possono essere esposte, ma non avendo una primary key occorre indicare esplicitamente i campi chiave nella configurazione dell’entity;
- le stored procedure si mappano come entity con l’azione execute e supportano un set ridotto di operazioni rispetto a una tabella (niente CRUD completo).
Sicurezza: autenticazione e autorizzazione
DAB non è “aperto” per default: un’entity è raggiungibile solo se una permission la autorizza esplicitamente.
Autenticazione — l’identità del chiamante arriva da un provider esterno; DAB valida il token e ne estrae i ruoli. I provider tipici sono Microsoft Entra ID (token JWT OAuth), l’autenticazione integrata di App Service / Static Web Apps (EasyAuth) e, solo per lo sviluppo locale, il Simulator.
Autorizzazione — è role-based, definita per ogni entity. Per ciascun ruolo si specificano le azioni consentite (create, read, update, delete; execute per le stored procedure). I ruoli chiave sono anonymous (chiamate senza autenticazione) e authenticated (qualsiasi utente autenticato), più eventuali ruoli custom. Il ruolo attivo per la richiesta si seleziona con l’header X-MS-API-ROLE, che deve corrispondere a un ruolo posseduto dall’identità.
Il controllo può scendere sotto il livello dell’entity:
- a livello di colonna, includendo o escludendo campi per ruolo;
- a livello di riga, con database policy che filtrano i record confrontando i claim del token con i valori delle righe.
Connessione al database e managed identity
DAB si collega al database tramite connection string. L’approccio consigliato in Azure è la managed identity: il servizio si autentica al database con la propria identità Entra, senza username e password nel file di configurazione. Questo elimina i segreti dalla configurazione e permette di applicare il least privilege, concedendo all’identità solo i permessi necessari sugli oggetti esposti.
Da ricordare: la managed identity riguarda l’autenticazione di DAB verso il database ed è cosa distinta dall’autenticazione degli utenti verso l’API. Eventuali altri segreti si tengono in Azure Key Vault, non in chiaro nella configurazione.
Trappole tipiche d’esame
- Connessione al database senza credenziali in chiaro → managed identity: scegli la managed identity Entra, non una password (nemmeno in Key Vault); è la soluzione passwordless che rimuove i segreti dalla connection string.
- Esporre una view → configura i campi chiave: la view non ha primary key, quindi i key-fields vanno dichiarati esplicitamente, altrimenti l’entity non si comporta come per una tabella.
- Esporre una stored procedure → azione execute: mappa la SP come entity con execute e aspettati operazioni limitate, non un CRUD completo.
- Impedire scritture agli anonimi → permission per ruolo: DAB non espone nulla di default; assegna al ruolo anonymous la sola read e le azioni di scrittura ai ruoli authenticated o custom.
- Restituire solo le righe dell’utente → database policy (item-level): il filtro per riga richiede una policy sui claim, non basta escludere colonne (che è controllo a livello di campo).
- Servono sia REST sia GraphQL → un’unica configurazione: non occorrono due servizi; entrambi i protocolli si generano dalla stessa definizione e si abilitano in modo indipendente.