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 + Actor Token (Business+) oppure pubblico (Free/Quick)

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.

Pattern di autenticazione

I requisiti di autenticazione dipendono dal piano e dal tipo di endpoint.

Endpoint pubblici (Quick e Free)

Gli endpoint pubblici non richiedono autenticazione. Qualsiasi client HTTP può inviare query:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(limit: 10) { id name price } }"}'

Gli endpoint pubblici sono soggetti a rate limiting per indirizzo IP per prevenire abusi.

Endpoint privati (Business ed Enterprise)

Gli endpoint privati richiedono due header di autenticazione:

Header	Valore	Scopo
Authorization	Bearer <API_KEY>	Identifica il progetto e autorizza l'accesso
X-Actor-Token	<ACTOR_TOKEN>	Identifica il consumer per il tracciamento della concorrenza

Autenticazione tramite API key

Le API key vengono emesse per progetto nello workspace di Mockomat. Ogni chiave:

• Ha un ambito limitato a un singolo progetto
• Può essere ruotata senza influire sulle altre chiavi
• Dispone dei propri limiti di concorrenza e di frequenza
• Può essere revocata in qualsiasi momento

Flusso degli actor token

Gli actor token gestiscono i consumer API simultanei. Il flusso di lavoro:

1. Richiedere un token — chiamare l'endpoint degli actor con la propria API key:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json"

Risposta:

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

2. Utilizzare il token — includerlo in tutte le richieste runtime successive:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(limit: 10) { id name price } }"}'

3. Scadenza del token — gli actor token hanno un timeout di inattività configurabile (predefinito 15 minuti). Ogni richiesta aggiorna il timeout. Se il token scade, richiederne uno nuovo.

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(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Query di dettaglio

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

Query con filtri

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "category", operator: EQ, value: "electronics" }
        ]
      }
    }
    limit: 50
  ) {
    id
    name
    price
  }
}

Query con ordinamento e paginazione

query {
  products(
    sort: { field: "price", direction: ASC }
    offset: 20
    limit: 20
  ) {
    id
    name
    price
  }
}

Query con relazioni annidate

query {
  customers(limit: 10) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
        unitPrice
      }
    }
  }
}

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 applicazione frontend, suite di test o altri consumer all'endpoint mock. Utilizzare variabili d'ambiente o file di configurazione per alternare tra gli endpoint Mockomat e i backend reali:

// environment.ts
export const environment = {
  apiUrl: 'https://api.mockomat.com/mock/my-project/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: Validate schema contract
    run: |
      # Recuperare lo schema corrente e confrontarlo con la baseline
      curl -s $API_URL -d '{"query":"{ __schema { types { name } } }"}' \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" > current-schema.json
      diff baseline-schema.json current-schema.json

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

Mockomat applica il rate limiting a più livelli per garantire un utilizzo equo e la stabilità della piattaforma.

Ambito	Free/Quick	Business	Enterprise
Per IP	60 req/min	N/A	N/A
Per API key	N/A	In base al piano	Personalizzato
Per tenant	N/A	N/A	Configurabile

Quando viene applicato il rate limiting, l'API restituisce HTTP 429 (Too Many Requests) con un header Retry-After che indica il tempo di attesa prima di riprovare.

Gestione degli errori

Risposte di errore comuni e come gestirle:

Stato HTTP	Codice errore	Significato	Azione
400	INVALID_QUERY	Errore di sintassi nella query GraphQL	Verificare la sintassi della query
401	UNAUTHORIZED	API key mancante o non valida	Verificare l'header dell'API key
401	SESSION_EXPIRED	L'actor token è scaduto	Richiedere un nuovo actor token
403	MAX_TENANT_SESSIONS_REACHED	Raggiunto il limite di sessioni simultanee	Attendere la scadenza di una sessione o rilasciarne una
404	PROJECT_NOT_FOUND	Slug del progetto non valido	Verificare l'URL dell'endpoint
429	RATE_LIMITED	Troppe richieste	Attendere la durata del Retry-After
429	MAX_ACTIVE_ACTORS_REACHED	Raggiunto il limite di actor simultanei	Attendere la scadenza di un actor

Formato della risposta di errore

{
  "error": "MAX_ACTIVE_ACTORS_REACHED",
  "maxActors": 5,
  "currentActors": 5,
  "retryAfterSeconds": 342
}

Controllare sempre il campo retryAfterSeconds quando disponibile: indica il tempo minimo di attesa prima di riprovare.

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.