Integratori

Questa sezione è destinata agli sviluppatori che collegano i flussi di lavoro di Mockomat a sistemi ingegneristici più ampi. Che si stia sviluppando un frontend che consuma una mock API di Mockomat, automatizzando la validazione del modello in CI/CD o integrando Mockomat nella pipeline di sviluppo del proprio team, questa pagina copre i pattern e le pratiche necessarie.

Panoramica degli endpoint API

Mockomat espone due superfici API distinte:

API	Endpoint	Scopo	Autenticazione
Management API	GET /graphql	CRUD dei progetti, configurazione del modello, gestione utenti	JWT (basata su sessione)
Mock Runtime API	POST /mock/{slug}/graphql	Interrogazione dei dati mock, test del comportamento del dominio	API key (Authorization: Bearer mck_…); progetti ospite: token di condivisione

La management API viene utilizzata dall'applicazione web Mockomat e dagli strumenti amministrativi. La mock runtime API è ciò che le applicazioni consumano come backend mock.

Autenticazione

Ogni richiesta alla mock runtime API di un progetto del proprio account porta una API key. Le richieste senza una chiave valida vengono rifiutate, qualunque sia l'impostazione di condivisione dell'anteprima del progetto: un link di condivisione apre la pagina di anteprima, non l'API.

API key

Le chiavi si creano nell'app in Account → Chiavi API, per il progetto attivo. Le API key sono incluse dal piano Professional in su. Ogni chiave:

• Appartiene a un solo progetto e risponde solo per quel progetto
• Viene mostrata per intero una sola volta, alla creazione: conservarla come una password
• Può avere una data di scadenza ed essere revocata in qualsiasi momento
• Ha uno scope: Runtime interroga i dati mock, Full raggiunge anche la management API; una chiave Management non può interrogare il runtime

Inviare la chiave come bearer token:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

Funziona anche l'header X-API-Key: mck_your_api_key.

Tenere la chiave fuori dal codice del browser

Una API key è un segreto. Chiamare la mock API da codice lato server, dalla CI o tramite un proxy del dev server che aggiunge l'header (step 4 del flusso di integrazione qui sotto); non distribuire mai la chiave in un bundle frontend.

Progetti ospite

Un progetto ospite (senza account) non ha API key. Il suo endpoint accetta il token di condivisione del progetto, quello del suo link di condivisione dell'anteprima, come parametro di query:

curl -X POST "https://api.mockomat.com/mock/my-guest-project/graphql?token=<share-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name } total } }"}'

Le richieste ospite vengono conteggiate nella quota giornaliera della sessione ospite.

Actor token (opzionali)

Gli actor token distinguono i consumer di una stessa API key, così da poter limitare l'uso simultaneo di una chiave. Sono opzionali: una richiesta con la sola API key viene servita.

1. Richiedere un token con la propria API key:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer mck_your_api_key"

Risposta:

{
  "actorToken": "act_abc123...",
  "expiresInSeconds": 900,
  "maxActors": 1,
  "currentActors": 1
}

2. Inviarlo con le richieste runtime:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

3. Scadenza per inattività — un token scade dopo 15 minuti senza richieste; ogni richiesta lo prolunga. Finché tutti gli slot actor di una chiave sono occupati, un nuovo actor riceve 429 MAX_ACTIVE_ACTORS_REACHED con un header Retry-After.

int-01-authenticationMissing

Punto di ingresso per l'integrazione con configurazione dell'autenticazione e del contesto.

Pattern di query

Query di elenco di base

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

Query di dettaglio

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Query con filtri

Gli argomenti sono parametri che l'operazione definisce nell'API design (qui minPrice su price con gte, category con eq); vedi il Runtime per operatori, ricerca e paginazione.

query {
  products(minPrice: 10, category: "electronics", pageSize: 50) {
    items {
      id
      name
      price
    }
    total
  }
}

Query con ordinamento e paginazione

query {
  products(sortField: "price", sortDirection: ASC, page: 2, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Query con relazioni annidate

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

Flusso di integrazione consigliato

1. Definire un ambito di dominio stabile

Prima di procedere all'integrazione, identificare quali entità e query l'applicazione consumerà. Non integrare un modello che cambia ancora frequentemente: attendere che la struttura di base sia stabile.

2. Fissare i contratti di denominazione e dei campi

Trattare lo schema GraphQL come un contratto. Una volta che l'applicazione dipende da nomi di query e strutture di campi specifici, le modifiche a tali nomi interromperanno l'integrazione. Utilizzare la vista API design in Mockomat per finalizzare i nomi delle query prima di collegare i consumer.

3. Validare il comportamento del runtime

Eseguire query esaustive attraverso l'anteprima del runtime e verificare che:

• I tipi di campo corrispondano a quelli attesi dall'applicazione
• L'annidamento delle relazioni funzioni correttamente
• I filtri restituiscano i sottoinsiemi previsti
• La paginazione produca separazioni di pagina pulite

4. Integrare i sistemi consumer

Collegare la propria test suite, il backend-for-frontend o altri consumer all'endpoint mock. Tenere endpoint e API key nella configurazione, così da poter passare da Mockomat al backend reale.

Un'app frontend raggiunge la mock API tramite il proxy del proprio dev server, che aggiunge la chiave lato server: in questo modo la chiave non finisce mai nel bundle:

// vite.config.ts — inoltra /mock-api a Mockomat e aggiunge l'API key
export default defineConfig({
  server: {
    proxy: {
      '/mock-api': {
        target: 'https://api.mockomat.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/mock-api/, '/mock/my-project'),
        headers: { Authorization: `Bearer ${process.env.MOCKOMAT_API_KEY}` },
      },
    },
  },
});

// environment.ts — l'app conosce solo il percorso del proxy
export const environment = {
  apiUrl: '/mock-api/graphql',
  // Passare al backend reale quando pronto:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Promuovere all'esportazione/implementazione

Quando il contratto della mock API è stabile e il frontend funziona correttamente, utilizzare la funzionalità di Esportazione per generare un backend di produzione che implementa lo stesso contratto.

int-02-ci-cd-flowMissing

Pattern di integrazione CI/CD con gate su modello e runtime.

CI/CD e automazione

Le mock API di Mockomat possono essere integrate nella pipeline CI/CD per validare il comportamento del frontend rispetto a un backend mock stabile.

Pattern di integrazione nelle pipeline

Validazione del contratto — eseguire controlli di confronto dello schema quando i modelli cambiano per rilevare breaking change prima che raggiungano i consumer.

Test di integrazione — puntare la suite di test di integrazione all'endpoint Mockomat per verificare il comportamento del frontend con dati mock realistici.

Validazione dell'anteprima — prima di eseguire il merge delle modifiche al modello, validare che il runtime produca i risultati attesi interrogando l'endpoint di anteprima in modo programmatico.

Esempio di step della pipeline

# Esempio di step della pipeline CI
steps:
  - name: Run integration tests against mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: npm run test:integration

  - name: Smoke-check the mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: |
      # Fa fallire lo step con 401/403/404: chiave mancante, revocata o di un altro progetto
      curl -sf "$API_URL" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query":"{ products(page: 1, pageSize: 1) { items { id } total } }"}'

Versionamento degli artefatti generati

Quando si utilizza la funzionalità di esportazione, versionare il codice backend generato insieme all'applicazione:

• Committare il codice generato in un branch o repository dedicato.
• Taggare le esportazioni con la versione del modello o la data.
• Includere un changelog che riassuma le modifiche al modello dall'ultima esportazione.
• Revisionare i diff del codice generato prima del merge nel branch principale.

Rate limiting

Alla mock runtime API si applicano tre limiti:

Ambito	Limite	Al raggiungimento
Per indirizzo IP	60 richieste al minuto	429 TOO_MANY_REQUESTS: riprovare dopo un minuto
Per account	La quota di richieste del piano (al giorno o al mese)	429 TOO_MANY_REQUESTS fino all'azzeramento della quota
Per API key	Actor simultanei, solo se si inviano actor token	429 MAX_ACTIVE_ACTORS_REACHED con un header Retry-After

I progetti ospite vengono conteggiati nella quota giornaliera della sessione ospite.

Gestione degli errori

Una richiesta rifiutata risponde con uno stato HTTP di errore e un corpo JSON. Decidere in base al suo code:

Stato HTTP	Codice	Significato	Azione
400	Bad Request	GraphQL non valido, operazione sconosciuta o disattivata, corpo malformato	Leggere message; correggere la query o il nome dell'operazione
401	UNAUTHENTICATED	Nessuna API key inviata (progetto ospite: token di condivisione mancante o errato)	Inviare Authorization: Bearer mck_…
401	API_KEY_INVALID	Chiave sconosciuta, revocata o eliminata	Creare una nuova chiave
401	API_KEY_EXPIRED	La data di scadenza della chiave è passata	Creare una nuova chiave
401	ACTOR_TOKEN_INVALID	X-Actor-Token malformato	Richiedere un token tramite /runtime/actors oppure omettere l'header
403	API_KEY_SCOPE_INSUFFICIENT	Chiave solo di gestione	Usare una chiave Runtime o Full
404	PROJECT_NOT_FOUND	Slug sconosciuto, o progetto a cui la chiave non appartiene (su /runtime/actors: il progetto della chiave è stato eliminato)	Verificare lo slug; usare una chiave di questo progetto
429	TOO_MANY_REQUESTS	Limite per IP o quota del piano raggiunti	Attendere, poi riprovare
429	MAX_ACTIVE_ACTORS_REACHED	Tutti gli slot actor della chiave sono occupati	Attendere la durata del Retry-After
429	RATE_LIMIT_EXCEEDED	Troppe richieste di actor token per una chiave (POST /runtime/actors)	Attendere la durata del Retry-After; riusare un token finché è attivo
503	QUERY_TIMEOUT	La query è durata troppo	Riprovare; restringere la query

Formato della risposta di errore

{
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID",
  "path": "/mock/my-project/graphql",
  "timestamp": "2026-10-05T09:30:00.000Z"
}

Un 429 con header Retry-After riporta anche retryAfter (secondi) nel corpo. Una richiesta servita risponde 200 con un corpo GraphQL; i problemi a livello di dati arrivano in errors[]: ad esempio extensions.code NOT_READY significa che la tabella non è ancora collegata ai dati.

Osservabilità e diagnostica

Monitorare questi segnali principali in tutti gli ambienti per mantenere l'affidabilità dell'integrazione:

Metriche chiave

• Stabilità delle query — le risposte sono strutturate in modo coerente? Prestare attenzione a modifiche inattese dello schema.
• Deriva della forma delle risposte — i tipi di campo o i livelli di annidamento cambiano tra gli aggiornamenti del modello?
• Affidabilità dei lookup delle relazioni — le query annidate si risolvono correttamente in modo coerente?
• Pattern di errori e timeout — determinate query sono costantemente lente o falliscono?
• Prossimità ai limiti di frequenza — quanto si è vicini al raggiungimento dei limiti di richieste o di concorrenza?

Raccomandazioni per il monitoraggio

• Registrare tutte le risposte API (o almeno i codici di stato e i tempi di risposta) nell'applicazione consumer.
• Configurare avvisi per le risposte HTTP 429 e 401: indicano problemi di configurazione o di capacità.
• Confrontare periodicamente gli schema delle risposte con una baseline per rilevare derive involontarie.
• Monitorare i pattern di refresh degli actor token per ottimizzare la strategia di concorrenza.

int-03-observabilityMissing

Checkpoint di osservabilità per l'affidabilità dell'integrazione.

Best practice

Developer / Integrator

Si trattino gli artefatti Mockomat come asset contract-first. Si mantengano l'intento del modello, il comportamento del runtime e le decisioni implementative tracciabili nello stesso change set. Quando il frontend dipende da una specifica forma di query, documentare tale dipendenza e validarla nella CI.

Nota sull'integrazione Enterprise

Enterprise User

Per gli ambienti Enterprise, utilizzare API key separate per ogni ambiente (sviluppo, staging, produzione). Questo consente di tracciare l'utilizzo per ambiente e di ruotare le chiavi in modo indipendente. Combinare con gli actor token per controllare esattamente quanti consumer simultanei supporta ogni ambiente.