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 il cui endpoint mock si apre con il suo token di condivisione
• Accesso completo alla board di modellazione, alla configurazione degli attributi e all'anteprima
• Lo stesso pool di dati condiviso e gli stessi tipi di mapping di ogni piano
• Un endpoint GraphQL live interrogabile immediatamente

Limitazioni:

• Il Tuo lavoro resta in questo browser finché la Tua sessione ospite di 24 ore non termina. Le 24 ore decorrono dall'inizio della Tua sessione ospite, che l'app avvia la prima volta che la apri in questo browser: un progetto creato più tardi ha quindi meno tempo. Una pulizia eseguita ogni ora elimina poi il progetto, che può quindi restare fino a un'ora in più.
• Cancellare i cookie fa perdere prima il Tuo lavoro; registrati per conservarlo — l'app offre di spostare il progetto nel Tuo account
• Un solo progetto alla volta
• Nessuna condivisione di team o gestione progetti
• Nessuna API key: l'endpoint si apre con il token di condivisione del progetto

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 (Starter, gratuito):

• 1 progetto salvato (di più a partire da Professional)
• Modelli persistenti che sopravvivono alle sessioni del browser
• 1.000 richieste API al giorno
• L'anteprima runtime di ogni progetto nell'app (le chiamate dal proprio codice richiedono API key, dal piano Professional in su)

Quando passare alla modalità Account:

• Quando il Tuo primo modello si rivela utile e vuoi conservarlo
• Quando vuoi condividere il Tuo lavoro — tramite link di anteprima e di collaborazione oppure, a partire da Professional, invitando i colleghi
• Quando vuoi iterare su più sessioni

Guida per Guest e Starter

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, il Tuo progetto resta finché non lo elimini e, a partire da Professional, puoi invitare il 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, Integer, Boolean, Date
Required	Deve sempre avere un valore	true per email, false per middleName
Searchable	Partecipa alla ricerca searchTerm	true per name, title

I flag Sortable e Filterable non modificano la mock API: puoi ordinare per qualsiasi attributo collegato a una colonna di dati, e il filtro usa i parametri che definisci su un'operazione nell'API design.

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:

Sorgente dati (SOURCE) — Dati importati

Collega l'attributo a una colonna del pool di dati condiviso — dataset importati: dati aperti dove esiste una fonte verificata, dati di esempio generati per i blueprint. Il runtime restituisce le righe importate e non inventa mai valori. Ideale per nomi, indirizzi, dati di prodotto, categorie, date e importi.

Costante (CONSTANT) — Valori fissi

Fissa un unico valore sull'attributo, es. uno stato predefinito ("active"). Il runtime lo restituisce su ogni riga, sia nelle righe di dati importati sia nelle righe composte da pool di valori.

Calcolato (COMPUTED) — Espressioni

Memorizza un'espressione su altri campi, es. un nome completo da nome e cognome. Il runtime non valuta le espressioni, quindi un campo calcolato non fa parte della risposta. L'editor degli attributi non offre più Calcolato; un attributo che ha già un mapping calcolato lo mantiene ed è contrassegnato come non valutato.

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 — Se una tabella non è collegata a dati importati, l'anteprima lo segnala e l'API non restituisce righe per essa. Collega la tabella prima di proseguire.

Comportamento di filtri e ordinamento — Prova un parametro che hai definito sull'operazione e ordina per un attributo con sortField. I risultati hanno senso?

Problemi comuni nell'anteprima

Problema	Causa probabile	Soluzione
Il campo restituisce null	Nessun mapping configurato	Collegare l'attributo a una colonna di dati (mapping Sorgente dati)
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	sortField non è il nome di un attributo mappato	Usare il nome di un attributo collegato a una colonna di dati
Il filtro restituisce tutti i record	L'operazione non definisce alcun parametro per quell'argomento	Aggiungere il parametro nell'API design

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 chiamarla da qualsiasi client GraphQL o HTTP con una API key del progetto: le API key sono incluse dal piano Professional in su. Un progetto ospite usa invece il suo token di condivisione (?token=…). I dettagli sono in Integratori.

L'endpoint del Tuo progetto è:

POST /mock/{your-project-slug}/graphql
Authorization: Bearer mck_your_api_key

Prova una semplice query di lista:

query {
  customers(page: 1, pageSize: 10) {
    items {
      id
      firstName
      lastName
      email
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

La risposta contiene le righe importate a cui puntano i Tuoi mapping, 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 righe del pool di dati
• 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.