Rotte e CRUD

Le rotte sono i punti d’ingresso della sua API. Sono raggruppate per risorsa, e può scriverle a mano o generarle a partire da un modello.

Definire una rotta

Una rotta porta un metodo, un percorso, dei parametri e delle risposte. Il percorso utilizza la sintassi {{param}} di Restorm: non appena digita {{id}} nel percorso, il parametro corrispondente appare; rimuoverlo lo elimina.

I parametri

La scheda Definizione di una rotta elenca i suoi parametri — i parametri di percorso (creati a partire dai placeholder {{param}}) e i parametri di query / header che aggiunge con Aggiungi un parametro. Ciascuno porta un nome, una posizione (in), il suo carattere obbligatorio, una descrizione e, facoltativamente, un esempio.

La cella Tipo è un combo: scelga un primitivo (string, integer, number, boolean) o uno degli enum denominati del design con un solo clic. Per i casi più ricchi, scelga Advanced… per aprire una piccola finestra dove può:

• rendere il parametro un array e scegliere il suo tipo di elemento (array<string>, …) — un parametro di query multivalore;
• dargli valori di enum inline (l’insieme consentito, elencato in chip) quando non è tipizzato da un enum denominato;
• Estrai in un enum denominato — promuovere questi valori inline in un enum condiviso (vedi Modelli ed enum).

Un parametro può anche essere collegato a una proprietà di modello (colonna Collegamento modello), di cui eredita il tipo, o essere marcato come deprecato. Ogni parametro — il suo tipo, il suo enum, la sua deprecazione — si ritrova nella documentazione generata e in ogni proiezione di protocollo.

Generare il CRUD

Dalle impostazioni di un modello, Genera il CRUD crea con un clic un gruppo di rotte nominato secondo il plurale del modello, con sei rotte:

Rotta	Metodo e percorso	Risposte
Elencare	GET / (paginato)	200
Recuperare	GET /{{id}}	200 · 404
Creare	POST /	201
Sostituire	PUT /{{id}}	200 · 404
Aggiornare	PATCH /{{id}}	200 · 404
Eliminare	DELETE /{{id}}	204 · 404

L’elenco è paginato (scostamento/offset, 20 elementi per impostazione predefinita, 100 al massimo). Ogni {{id}} è automaticamente collegato all’identificatore del modello.

La finestra di dialogo Genera il CRUD propone due opzioni:

• Sostituire le rotte esistenti — per evitare i duplicati se rigenera.
• Proteggere le rotte di scrittura tramite autenticazione — la creazione, la sostituzione, l’aggiornamento e l’eliminazione richiedono allora un token (bearer), mentre le letture restano pubbliche.

Ricorda inoltre che il CRUD è servito in ogni protocollo: rotte REST, query e mutazioni GraphQL, metodi gRPC, set di entità OData e operazioni SOAP (vedi Servire il design come mock).

Generare le rotte di ricerca

Per ogni proprietà marcata come searchable, Genera le rotte di ricerca aggiunge un parametro di query collegato alla rotta di elenco del modello (e crea quella rotta se non esiste ancora).

Autenticazione

L’autenticazione si regola su tre livelli: un valore predefinito del design, un’autenticazione richiesta per gruppo, e una sostituzione per rotta (che eredita dal gruppo predefinito). Le modalità disponibili sono Nessuna, Bearer (JWT), Chiave API (header) e Basic.

Le etichette

Le etichette raggruppano le rotte per la documentazione e l’esportazione OpenAPI. Vivono a due livelli: una rotta porta le proprie etichette (la sua scheda Definizione), e un gruppo porta etichette condivise (le sue impostazioni) applicate a ciascuna delle sue rotte. Le etichette effettive di una rotta sono l’unione delle due — un’etichetta comune a tutto un gruppo si pone quindi preferibilmente una sola volta sul gruppo. Quando trasforma un’API importata in un design, un’etichetta presente su tutte le rotte di un gruppo viene automaticamente sollevata sul gruppo.

La deprecazione

Una rotta (come una proprietà o un parametro) può essere marcata come deprecata dalle sue Impostazioni. Una rotta deprecata appare in grigio nell’elenco delle Rotte e nei client generati, e porta un avviso di deprecazione sulla sua scheda. Il flag si propaga in ogni proiezione di protocollo — il deprecated di OpenAPI, la direttiva @deprecated di GraphQL, i descrittori SOAP e gRPC, e i metadati OData — affinché i consumatori di qualsiasi protocollo servito lo vedano.