Guida introduttiva

Questa sezione aiuta un nuovo utente a passare dal primo accesso a un primo workflow affidabile in una sola sessione. Al termine, avrà un modello di dominio funzionante con dati mappati, un'API GraphQL live da interrogare e una chiara comprensione dei passi successivi.

Cosa costruirà

In questa guida:

1. Accederai a Mockomat e sceglierai la Tua modalità di lavoro.
2. Creerai una tabella di dominio che rappresenta un concetto di business reale.
3. Aggiungerai attributi con tipi e mapping appropriati.
4. Stabilirai almeno una relazione con un'altra entità.
5. Visualizzerai il Tuo modello in anteprima tramite il runtime live.
6. Verificherai che l'API restituisca le strutture dati attese.

L'intero processo richiede circa 15 minuti.

gs-01-start-entryMissing

Punto di ingresso dalla landing page al workspace dell'applicazione.

Passo 1: Scegliere la modalità di accesso

Mockomat offre due modalità di accesso, ciascuna pensata per una fase di lavoro diversa:

Modalità Guest (avvio rapido)

La modalità Guest è il percorso più rapido verso un mock API funzionante. Nessuna registrazione, nessuna configurazione — basta aprire Mockomat e iniziare a modellare.

Cosa ottieni:

• Un progetto temporaneo con un endpoint pubblico
• Accesso completo alla board di modellazione, alla configurazione degli attributi e all'anteprima
• Accesso a tutti i tipi di mapping dei dati (dataset reali, Faker, costanti)
• Un endpoint GraphQL live interrogabile immediatamente

Limitazioni:

• Il Tuo lavoro è legato alla sessione del browser — chiudere la scheda o cancellare i cookie comporta la perdita dei progressi
• Un solo progetto alla volta
• Nessuna condivisione di team o gestione progetti
• Solo endpoint pubblico (nessun controllo di accesso privato)

La modalità Guest è ideale per la validazione rapida di idee, demo e per valutare se Mockomat si adatta al Tuo workflow.

Modalità Account (workspace persistente)

La modalità Account aggiunge persistenza, gestione dei progetti e la possibilità di ampliare l'utilizzo nel tempo.

Cosa ottieni (piano Free):

• Fino a 5 progetti salvati
• Modelli persistenti che sopravvivono alle sessioni del browser
• Cronologia dei progetti e possibilità di rivisitare e iterare
• 1.000 richieste API al giorno
• Endpoint pubblici

Quando passare alla modalità Account:

• Quando il Tuo primo modello si rivela utile e vuoi conservarlo
• Quando hai bisogno di condividere il lavoro con i colleghi
• Quando vuoi iterare su più sessioni

Guida per utenti free

Free User

Inizia in modalità Guest per testare rapidamente uno scenario di dominio concreto. Si concentri sulla chiarezza dei nomi, sui campi obbligatori e sul comportamento dei dati. Se il Tuo modello regge dopo alcune query, crea un account free per salvarlo.

Guida per utenti registrati

Registered User

Passa alla modalità Account una volta che il Tuo primo modello è utile. Persistenza e ripetibilità diventano più preziose della sola velocità istantanea. Con un account, puoi confrontare le versioni del Tuo modello nel tempo e condividere il contesto all'interno del Tuo team.

gs-02-guest-workspaceMissing

Workspace Guest con la prima tabella di dominio.

Passo 2: Modellare una porzione reale di dominio

Una porzione di dominio è un sottoinsieme piccolo e coerente del Tuo modello di business. Inizia con una o due entità che rappresentano qualcosa di reale nel Tuo sistema.

Scegliere nomi significativi

Evita nomi di esempio generici. Utilizza il linguaggio di business reale che il Tuo team già utilizza:

Buoni esempi:

• Customer, Subscription, Invoice
• Order, Payment, Shipment
• Product, Category, Review
• Employee, Department, TimeEntry

Da evitare:

• Table1, TestEntity, MyModel
• Data, Item, Thing

Nomi significativi rendono il Tuo modello auto-documentante e immediatamente utile per le discussioni di team.

Aggiungere attributi

Ogni entità necessita di attributi che descrivano i suoi dati. Quando aggiungi attributi, considera:

Proprietà	Scopo	Esempio
Name	Identificatore descrittivo	firstName, totalAmount, isActive
Type	Tipo di dato	string, number, boolean, date
Required	Deve sempre avere un valore	true per email, false per middleName
Sortable	Può essere usato per l'ordinamento	true per createdAt, price
Searchable	Partecipa alla ricerca	true per name, title
Filterable	Supporta espressioni di filtro	true per status, category

Suggerimento pratico: Inizia con 4-6 attributi principali per entità. Potrai sempre aggiungerne altri in seguito, ma un modello focalizzato fornisce un feedback migliore rispetto a uno ampio e superficiale.

Scegliere i mapping dei campi

Ogni attributo necessita di una fonte dati. Mockomat supporta tre tipi di mapping:

OFF_FIELD — Dati da dataset reali

Mappa un campo da un dataset del mondo reale (es. Open Food Facts). Produce valori realistici e diversificati. Ideale per nomi di prodotti, categorie, dati nutrizionali, codici a barre.

FAKE — Dati sintetici (Faker)

Genera dati realistici ma fittizi: nomi, email, indirizzi, date, prezzi. Ideale per dati personali, importi finanziari, timestamp, recapiti.

CONST — Valori fissi

Ogni record riceve lo stesso valore. Ideale per stati predefiniti ("active"), configurazioni fisse, valori segnaposto durante la modellazione iniziale.

gs-03-first-tableMissing

Creazione della prima tabella e configurazione degli attributi.

Stabilire una relazione

Una volta modellata un'entità, aggiungi una seconda entità e le colleghi:

1. Crea una seconda tabella (ad esempio, Order se la prima era Customer).
2. Definisci il tipo di relazione: un cliente ha molti ordini (1:n)? Un ordine appartiene a esattamente un cliente?
3. Imposta la direzione: quale entità possiede la relazione?

Le relazioni sono fondamentali per testare come la Tua API gestisce i dati annidati. Un modello con almeno una relazione offre un feedback nell'anteprima molto più ricco.

gs-03b-first-relationMissing

Prima configurazione di relazione tra due entità.

Passo 3: Validare tramite anteprima

L'anteprima non serve solo per le demo. È un checkpoint di qualità del modello. Ogni volta che modifichi il Tuo modello, esegui un'anteprima per confermare che la modifica si comporti come previsto.

Cosa verificare

Leggibilità dei campi — I nomi dei campi restituiti hanno senso? Sono coerenti (tutti in camelCase, senza abbreviazioni)?

Coerenza della struttura dati — Ogni campo restituisce il tipo atteso? Le stringhe sono effettivamente stringhe, i numeri effettivamente numeri?

Comportamento delle relazioni — Quando interroga un'entità padre, le entità figlio appaiono correttamente annidate? La cardinalità è corretta (array per 1:n, oggetto singolo per 1:1)?

Segnali di mapping mancanti — L'anteprima mostra suggerimenti per gli attributi che non hanno ancora una fonte dati. Li risolva prima di proseguire.

Comportamento di filtri e ordinamento — Prova a filtrare per un campo contrassegnato come filterable. Prova a ordinare per un campo sortable. I risultati hanno senso?

Problemi comuni nell'anteprima

Problema	Causa probabile	Soluzione
Il campo restituisce null	Nessun mapping configurato	Assegnare un mapping OFF_FIELD, FAKE o CONST
La relazione restituisce un array vuoto	Relazione non definita correttamente	Verificare la direzione della relazione e l'entità di destinazione
L'ordinamento non ha effetto	Campo non contrassegnato come sortable	Abilitare il flag sortable sull'attributo
Il filtro restituisce tutti i record	Campo non contrassegnato come filterable	Abilitare il flag filterable sull'attributo

gs-04-first-previewMissing

Prima esecuzione dell'anteprima con campi mappati e non mappati.

Passo 4: Interrogare la Tua API

Una volta che l'anteprima è corretta, la Tua mock API è già attiva. Puoi interrogarla da qualsiasi client GraphQL o direttamente dalla Tua applicazione frontend.

L'endpoint del Tuo progetto è:

POST /mock/{your-project-slug}/graphql

Prova una semplice query di lista:

query {
  customers(offset: 0, limit: 10) {
    id
    firstName
    lastName
    email
    orders {
      id
      totalAmount
      createdAt
    }
  }
}

La risposta conterrà dati realistici derivati dai mapping configurati, con le relazioni risolte automaticamente.

gs-04b-first-queryMissing

Prima query GraphQL verso l'endpoint mock live.

Passo 5: Decidere il percorso successivo

Dopo il primo ciclo riuscito di modello e query, hai diverse direzioni possibili:

• Approfondire il modello — aggiungere più entità, perfezionare gli attributi, stabilire ulteriori relazioni.
• Configurare l'esposizione API — definire quali operazioni sono disponibili, impostare le convenzioni di denominazione delle query.
• Procedere verso l'export — se il modello è sufficientemente stabile, esplorare la generazione del codice per ottenere un backend NestJS pronto per la produzione.
• Utilizzare i blueprint — esplorare i template di dominio predefiniti per accelerare i progetti futuri.
• Condividere con il team — creare un account (se in modalità Guest) e invitare i collaboratori.

Guida per utenti paid

Paid User

Dopo la prima validazione, standardizza la denominazione delle tabelle e la strategia operativa. Questo facilita la collaborazione e la governance nel tempo. Definisci le convenzioni presto — il loro valore cresce progressivamente con la crescita del progetto.

Guida per utenti enterprise

Enterprise User

Tratta il primo workflow come un pattern pilota. Definisci le convenzioni presto (denominazione, ownership, criteri di validazione) e le riutilizzi tra i team. Un pilota ben strutturato diventa il template per ogni progetto successivo.

gs-05-next-stepsMissing

Punto decisionale dopo il primo ciclo di anteprima riuscito.

Cosa hai ottenuto

Dopo aver completato questa guida, disponi di:

• Un modello di dominio con almeno un'entità, attributi significativi e mapping dei dati configurati
• Un endpoint API GraphQL live che restituisce dati realistici
• La validazione che il Tuo modello si comporta come previsto sotto query reali
• Una chiara comprensione del workflow modello -> anteprima -> query

Da qui, esplora i Concetti fondamentali per comprendere l'architettura alla base di ciò che hai appena costruito, oppure immergiti nel Workspace per una guida dettagliata agli strumenti di modellazione.