Il costruttore di API

Ogni API di Keplin è un'operazione GraphQL dell'app: una query che legge dati o una mutation che li scrive. Le schermate dell'app stessa, i report, i workflow e i sistemi esterni chiamano tutti le stesse API — ciò che definisci qui è l'unica strada di entrata e uscita dei dati dell'applicazione.

Un'API può avere una di due nature:

Natura	Che cos'è	Dove si approfondisce
Pipeline	Una sequenza di passaggi (Query SQL, Chiamata HTTP, Script) che gira in ordine; il risultato dell'ultimo passaggio è la risposta.	Questa pagina
Tabella	Un blocco unico collegato a una tabella del modello dati, che genera le operazioni di lettura e scrittura (get/add/update/delete) per te.	L'API GraphQL del modello

Questa pagina copre il costruttore in sé: creare l'API, definire gli argomenti, montare la pipeline, provare senza salvare e pubblicare.

#Dove vivono le API

Dentro un'app, apri il pannello Codice nella barra laterale. La sezione API elenca le API esistenti — puoi organizzarle in cartelle con Nuova cartella — e ognuna si apre come scheda dello spazio di lavoro. L'app ha anche una pagina di riepilogo con l'elenco completo, il tipo e lo stato di ogni API, e l'indirizzo a cui vengono servite.

#Creare un'API

1. Nel pannello Codice, sulla riga API, premi il pulsante + (Nuova API). Il pulsante Nuova API della pagina di riepilogo ti porta allo stesso posto: lo spazio di lavoro dell'app.
2. Dai un Nome. Il nome è il campo GraphQL che i client chiameranno, perciò segui la regola: lettere, numeri e underscore, senza iniziare con un numero — per esempio getOportunidadesPorConta.
3. Premi Crea API. L'API nasce come bozza e il costruttore si apre subito dopo — è lì che decidi la natura (blocchi SQL, HTTP, script o tabella).

#Il costruttore a colpo d'occhio

L'intestazione del costruttore mostra il nome, un badge con il tipo (query, mutation o tabella) e lo stato (pubblicata o bozza). A destra restano i comandi che valgono per l'API intera:

Comando	Che cosa fa
Pubblicata	Attiva/disattiva la pubblicazione. Un'API in bozza è visibile solo a chi la costruisce; i client esterni non la vedono.
Pubblica (senza sessione)	Rende l'API accessibile senza sessione né chiave API — per le schermate pubbliche dell'app. Vedi API pubbliche.
Salva	Salva l'API così com'è. Salvare è sempre possibile con nome e argomenti validi — anche il lavoro a metà si salva.

Sotto, il lavoro si divide in tre schede:

Scheda	Per che cosa
Costruisci	Identificazione, argomenti e la pipeline di passaggi.
Prova	Eseguire la pipeline in bozza e sperimentare l'API come un client.
Docs	Esempi pronti da copiare per chiamare l'API dall'esterno.

#Identificazione

Nella sezione Identificazione definisci:

• Operazione — Query — legge dati o Mutation — scrive dati. La scelta è semantica e pratica: le mutation chiedono conferma prima di ogni esecuzione di test, perché scrivono davvero.
• Nome — il campo GraphQL. Se il nome non è valido, il costruttore avvisa: "camelCase semplice: lettere, numeri e underscore, senza iniziare con un numero."

In un'API di Tabella non c'è scelta dell'operazione — le operazioni derivano dalle azioni CRUD che attivi nel blocco Tabella.

#Argomenti

La sezione Argomenti dichiara i parametri che i client passano all' API. Ogni argomento ha:

Colonna	Che cos'è
Nome	Identificatore dell'argomento (lettere, numeri, underscore; non inizia con un numero).
Tipo	Uno fra: String, Int, Float, Boolean, ID, JSON, Upload.
Obbl.	Se il client è obbligato a inviare l'argomento.
Default	Valore usato quando il client non invia nulla.
Valore di test	Solo per il pulsante Esegui della scheda Prova — non tocca i client.

Dentro la pipeline, gli argomenti restano disponibili come :nome nei passaggi SQL e HTTP, e come input["args"]["nome"] nel passaggio Script.

#File come argomento (tipo Upload)

Un argomento di tipo Upload riceve un file. In quel caso la colonna Default lascia il posto alla scelta dell'archiviazione: Dell'app usa l' archiviazione predefinita; in alternativa scegli una delle archiviazioni configurate nelle impostazioni dell'app (sezione Archiviazione). Così, un' API che riceve fatture e un'altra che riceve fotografie non devono conservare i file nello stesso posto.

Che cosa succede quando l'API viene chiamata con un file:

1. Il file viene salvato nell'archiviazione scelta.
2. Nella pipeline, l'argomento smette di essere il file grezzo e diventa un riferimento con filename, mimeType, size e un token — è questo che un passaggio Script riceve in input["args"]["nomeDoArg"].
3. L'app conserva il record del file, come qualsiasi altro file inviato dagli utenti.

Per provare, la colonna del valore di test si trasforma in un selettore di file — scegline uno dal tuo computer e premi Esegui.

Dall'esterno, il file si invia come variabile multipart della richiesta GraphQL (il formato standard di upload GraphQL); dentro la piattaforma, le schermate se ne occupano per te.

#La pipeline

La sezione Pipeline è dove l'API prende corpo. Le regole sono semplici:

• I passaggi girano in ordine; il risultato dell'ultimo è la risposta dell'API.
• Ogni passaggio (dal secondo in poi) può ricevere il risultato del precedente — il badge "riceve il risultato del passaggio N" lo ricorda.
• Nei passaggi SQL e HTTP, il risultato precedente è in :prev, e accetta percorsi: :prev.id, :prev.0.id.
• Aggiungi passaggi con i pulsanti Query SQL, Chiamata HTTP e Script; il pulsante Tabella converte l'API alla natura di tabella (e non si combina con gli altri blocchi).

Finché non ci sono blocchi, la sezione suggerisce la strada: il default è una Tabella del modello; in alternativa, si costruisce una pipeline con i passaggi descritti qui sotto.

#Passaggio Query SQL

1. Scegli il Datasource — uno dei database registrati nell'app. Senza datasource, il passaggio mostra la scorciatoia per crearne il primo.
2. Scrivi la query nell'editor. Scrivi : per completare automaticamente gli argomenti; l'editor conosce le tabelle e le colonne del datasource scelto e le suggerisce mentre scrivi.
3. Se la query restituisce per natura una sola riga (un totale, un record per chiave), attiva Restituisci solo la prima riga — la risposta passa da elenco a oggetto.

I valori di :argumento e :prev vanno sempre parametrizzati al database — mai concatenati nel testo della query. Questo ti protegge dall' iniezione SQL senza alcuno sforzo.

#Passaggio Chiamata HTTP

Per parlare con servizi esterni:

1. Scegli il Metodo (GET, POST, PUT, PATCH o DELETE) e compila l' URL — es.: https://api.esempio.it/clienti/:clienteId.
2. Aggiungi gli Headers con Aggiungi header — per esempio Authorization con il valore Bearer :token.
3. Nei metodi con corpo, compila il Body; attiva Invia come JSON perché il corpo parta con il tipo di contenuto corretto.

:nomeDoArg e :prev vengono sostituiti nell'URL, negli header e nel body.

#Passaggio Script

Il passaggio Script esegue uno script dell'app — la stessa logica che puoi eseguire a mano o per pianificazione, ora come parte di un'API:

1. Scegli lo Script nell'elenco (l'elenco mostra il nome e il linguaggio di ognuno; appaiono solo gli script attivi). Senza script, il passaggio mostra la scorciatoia per crearne il primo.
2. Decidi se il passaggio Riceve il risultato del passaggio precedente — nel primo passaggio della pipeline questo interruttore non si applica.

Il contratto con lo script è chiaro: gli argomenti dell'API arrivano in input["args"], il risultato del passaggio precedente in input["prev"], e il valore restituito dalla funzione main(input) prosegue verso il passaggio successivo (o è la risposta, se è l'ultimo passaggio).

#Riordinare e rimuovere passaggi

Ogni card di passaggio ha le frecce per Sposta su / Sposta giù e un cestino per Rimuovi passaggio. Cambiare la pipeline invalida il risultato dell'ultimo test — torna a Esegui per vedere risultati freschi.

#Provare senza salvare

La scheda Prova ha due strumenti. Il primo, Prova la pipeline (bozza), esegue la pipeline COSÌ COM'È nel costruttore, senza salvare:

1. Compila i valori di test degli argomenti (nella sezione Argomenti).
2. Premi Esegui. In una mutation, il costruttore chiede conferma — "Eseguire la mutation adesso?" — perché il test gira davvero contro i datasource e una mutation fa scritture reali.
3. Leggi il risultato: il badge Riuscito/Errore con la durata, la Risposta completa (le risposte molto grandi appaiono troncate), e con più di un passaggio, il Risultato per passaggio — ogni passaggio con badge ok/errore, per vedere esattamente dove la pipeline si è rotta.
4. Se i passaggi hanno scritto log (uno script che stampa, per esempio), appaiono nel blocco Log.

#Il return type

Il return type è la forma della risposta nello schema GraphQL — è lui a dire ai client quali campi possono selezionare. Il costruttore lo deduce dal risultato reale: dopo ogni esecuzione guarda il blocco Return type (inferito). Se differisce da quello salvato, appare l'avviso "Questo return type non è ancora salvato." con il pulsante Salva return type — e un punto ambra sul pulsante Salva ti ricorda la stessa cosa.

#Sperimentare come un client

Il secondo strumento della scheda Prova è un ambiente GraphQL interattivo puntato all'endpoint dell'app — scrivi operazioni, hai il completamento automatico dello schema e vedi le risposte. Siccome sei autenticato, appaiono anche le bozze. Il pulsante Apri in finestra apre lo stesso ambiente in una scheda del browser. I dettagli restano nel capitolo successivo, in L'API GraphQL del modello.

#Pubblicare

L'interruttore Pubblicata controlla chi vede l'API:

• Bozza — la vede solo chi la costruisce (nelle sessioni autenticate, le operazioni appaiono contrassegnate come bozza). I client esterni e gli utenti dell'app non la vedono, nemmeno elencando lo schema.
• Pubblicata — entra nello schema per tutti i client con accesso.

Per salvare come pubblicata, l'API deve essere completa. Il costruttore mostra i blocchi accanto all'intestazione — per esempio "Passaggio 2: l'SQL è vuoto." oppure, in un'API di tabella, "Per salvare come pubblicata, scegli la tabella e almeno un'azione CRUD." Questi avvisi non impediscono mai il Salva come bozza: impediscono solo la pubblicazione.

#La documentazione generata (scheda Docs)

La scheda Docs risponde alla domanda "come chiamo questo dall'esterno?". È generata dalla versione salvata — salva prima l'API — e mostra:

• L'endpoint (POST /api/graphql/gestao-clientes), con il pulsante di copia.
• La nota di autenticazione: l'header x-api-key è obbligatorio per i client esterni — le chiavi si generano in Chiavi API. Nella scheda Prova (sessione interna) non serve.
• Una voce per ogni operazione dell'API con quattro blocchi pronti da copiare: Query GraphQL, Variables, curl e JavaScript (fetch). In un'API di tabella, appaiono tutte le operazioni attive (get, count, add, update, delete).

#Perché no…?

• Perché non riesco a pubblicare? Manca il completamento della pipeline — leggi i blocchi accanto all'intestazione: ogni passaggio mancante è elencato con il numero e il motivo.
• Perché l'Esegui mi chiede conferma? L'API è una mutation: il test fa scritture reali. Assicurati di puntare a dati di test.
• Perché non vedo la mia API nuova nell'ambiente di test GraphQL? Salva prima — l'ambiente risponde sulla versione salvata. Le bozze salvate appaiono (sei autenticato); per i client esterni, solo quando pubblicherai.
• Perché non posso aggiungere un passaggio SQL a un'API di Tabella? Un'API Tabella non si combina con altri blocchi — rimuovi prima il blocco Tabella (o i passaggi, nel senso inverso).