Integratoren

Dieser Abschnitt richtet sich an Entwickler, die Mockomat-Workflows in umfassendere Engineering-Systeme einbinden. Ob Du ein Frontend erstellst, das eine Mockomat-Mock-API konsumiert, Modellvalidierung in CI/CD automatisierst oder Mockomat in die Entwicklungspipeline Deines Teams integrierst — diese Seite behandelt die Muster und Praktiken, die Du benötigst.

API-Endpunkte-Übersicht

Mockomat stellt zwei unterschiedliche API-Oberflächen bereit:

API	Endpunkt	Zweck	Authentifizierung
Management-API	GET /graphql	Projekt-CRUD, Modellkonfiguration, Nutzerverwaltung	JWT (sitzungsbasiert)
Mock-Runtime-API	POST /mock/{slug}/graphql	Mock-Daten abfragen, Domain-Verhalten testen	API-Schlüssel (Authorization: Bearer mck_…); Gastprojekte: Freigabe-Token

Die Management-API wird von der Mockomat-Webanwendung und administrativen Tools verwendet. Die Mock-Runtime-API ist das, was Deine Anwendungen als Mock-Backend konsumieren.

Authentifizierung

Jede Anfrage an die Mock-Runtime-API eines Projekts in Deinem Konto trägt einen API-Schlüssel. Anfragen ohne gültigen Schlüssel werden abgewiesen, unabhängig von der Vorschau-Freigabe des Projekts — ein Freigabe-Link öffnet die Vorschauseite, nicht die API.

API-Schlüssel

Schlüssel erstellst Du in der App unter Konto → API-Schlüssel, jeweils für das aktive Projekt. API-Schlüssel gibt es ab dem Professional-Tarif. Jeder Schlüssel:

• Gehört zu genau einem Projekt und gilt nur für dieses
• Wird nur einmal vollständig angezeigt, beim Erstellen — bewahre ihn wie ein Passwort auf
• Kann ein Ablaufdatum haben und jederzeit widerrufen werden
• Hat einen Scope: Runtime fragt Mock-Daten ab, Full erreicht zusätzlich die Management-API; ein Management-Schlüssel kann die Runtime nicht abfragen

Sende den Schlüssel als 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 } }"}'

Der Header X-API-Key: mck_your_api_key funktioniert ebenso.

Schlüssel nicht in Browser-Code

Ein API-Schlüssel ist ein Geheimnis. Rufe die Mock-API aus serverseitigem Code, aus der CI oder über einen Dev-Server-Proxy auf, der den Header ergänzt (Schritt 4 des Integrationsablaufs unten) — liefere den Schlüssel nie in einem Frontend-Bundle aus.

Gastprojekte

Ein Gastprojekt (ohne Konto) hat keine API-Schlüssel. Sein Endpunkt akzeptiert das Freigabe-Token des Projekts — das Token aus seinem Vorschau-Freigabe-Link — als Query-Parameter:

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 } }"}'

Gastanfragen zählen gegen das tägliche Anfragekontingent der Gastsitzung.

Actor-Tokens (optional)

Actor-Tokens unterscheiden die Konsumenten eines API-Schlüssels, damit sich die gleichzeitige Nutzung eines Schlüssels begrenzen lässt. Sie sind optional — eine Anfrage nur mit dem API-Schlüssel wird bedient.

1. Token anfordern — mit Deinem API-Schlüssel:

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

Antwort:

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

2. Token mitsenden — bei Deinen Runtime-Anfragen:

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. Ablauf bei Inaktivität — ein Token läuft nach 15 Minuten ohne Anfragen ab; jede Anfrage verlängert es. Solange alle Actor-Plätze eines Schlüssels belegt sind, erhält ein neuer Actor 429 MAX_ACTIVE_ACTORS_REACHED mit einem Retry-After-Header.

int-01-authenticationMissing

Integrations-Einstieg mit Authentifizierung und Kontext-Setup.

Abfragemuster

Einfache Listenabfrage

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

Detailabfrage

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

Gefilterte Abfrage

Die Argumente sind Parameter, die die Operation im API-Design definiert (hier minPrice auf price mit gte, category mit eq); Operatoren, Suche und Paginierung beschreibt die Runtime.

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

Sortierte und paginierte Abfrage

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

Verschachtelte Relationsabfrage

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

Empfohlener Integrationsablauf

1. Stabilen Domain-Umfang definieren

Vor der Integration identifiziere, welche Entitäten und Abfragen Deine Anwendung konsumieren wird. Integriere nicht gegen ein Modell, das sich noch häufig ändert — warte, bis die Kernstruktur stabil ist.

2. Benennung und Feldverträge festlegen

Behandle das GraphQL-Schema als Vertrag. Sobald Deine Anwendung von bestimmten Abfragenamen und Feldstrukturen abhängt, werden Änderungen an diesen Namen die Integration brechen. Verwende die API-Design-Ansicht in Mockomat, um Abfragenamen zu finalisieren, bevor Du Konsumenten verbindest.

3. Runtime-Verhalten validieren

Führe umfassende Abfragen über die Runtime-Vorschau aus und verifiziere:

• Feldtypen stimmen mit den Erwartungen Deiner Anwendung überein
• Relationsverschachtelung funktioniert korrekt
• Filter geben die erwarteten Teilmengen zurück
• Paginierung erzeugt saubere Seitengrenzen

4. Konsumentensysteme integrieren

Verbinde Deine Testsuite, Dein Backend-for-Frontend oder andere Konsumenten mit dem Mock-Endpunkt. Halte Endpunkt und API-Schlüssel in der Konfiguration, damit Du zwischen Mockomat und Deinem echten Backend wechseln kannst.

Eine Frontend-App erreicht die Mock-API über den Proxy ihres Dev-Servers, der den Schlüssel serverseitig ergänzt — so landet der Schlüssel nie im Bundle:

// vite.config.ts — leitet /mock-api an Mockomat weiter und ergänzt den API-Schlüssel
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 — die App kennt nur den Proxy-Pfad
export const environment = {
  apiUrl: '/mock-api/graphql',
  // Zum echten Backend wechseln, wenn bereit:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Zum Export/zur Implementierung übergehen

Wenn der Mock-API-Vertrag stabil ist und Dein Frontend korrekt dagegen arbeitet, verwendest Du die Export-Funktion, um ein Produktions-Backend zu generieren, das denselben Vertrag implementiert.

int-02-ci-cd-flowMissing

CI/CD-Integrationsmuster mit Modell- und Runtime-Gates.

CI/CD und Automatisierung

Mockomat-Mock-APIs können in Deine CI/CD-Pipeline integriert werden, um Frontend-Verhalten gegen ein stabiles Mock-Backend zu validieren.

Pipeline-Integrationsmuster

Vertragsvalidierung — führst Du Schema-Vergleichsprüfungen durch, wenn Modelle sich ändern, um Breaking Changes zu erkennen, bevor sie Konsumenten erreichen.

Integrationstests — richte Deine Integrations-Testsuite auf den Mockomat-Endpunkt, um Frontend-Verhalten gegen realistische Mock-Daten zu verifizieren.

Vorschau-Validierung — vor dem Mergen von Modelländerungen validiere, dass die Runtime erwartete Ergebnisse liefert, indem Du den Vorschau-Endpunkt programmatisch abfragst.

Beispiel-Pipeline-Schritte

# Beispiel CI-Pipeline-Schritt
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: |
      # Schlägt bei 401/403/404 fehl: fehlender, widerrufener oder projektfremder Schlüssel
      curl -sf "$API_URL" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query":"{ products(page: 1, pageSize: 1) { items { id } total } }"}'

Generierte Artefakte versionieren

Wenn Du die Export-Funktion verwenden, versioniere den generierten Backend-Code zusammen mit Deiner Anwendung:

• Generierten Code in einen dedizierten Branch oder ein separates Repository committen.
• Exporte mit der Modellversion oder dem Datum taggen.
• Ein Changelog mit einer Zusammenfassung der Modelländerungen seit dem letzten Export beifügen.
• Generierte Code-Diffs vor dem Merge in main reviewen.

Ratenbegrenzung

Für die Mock-Runtime-API gelten drei Limits:

Bereich	Limit	Bei Erreichen
Pro IP-Adresse	60 Anfragen pro Minute	429 TOO_MANY_REQUESTS — nach einer Minute erneut versuchen
Pro Konto	Das Anfragekontingent Deines Tarifs (pro Tag oder pro Monat)	429 TOO_MANY_REQUESTS, bis das Kontingent zurückgesetzt wird
Pro API-Schlüssel	Gleichzeitige Actors — nur wenn Du Actor-Tokens sendest	429 MAX_ACTIVE_ACTORS_REACHED mit einem Retry-After-Header

Gastprojekte zählen gegen das tägliche Kontingent der Gastsitzung.

Fehlerbehandlung

Eine abgewiesene Anfrage antwortet mit einem HTTP-Fehlerstatus und einem JSON-Body. Entscheide anhand seines code:

HTTP-Status	Code	Bedeutung	Aktion
400	Bad Request	Ungültiges GraphQL, unbekannte oder deaktivierte Operation, fehlerhafter Body	message lesen; Abfrage oder Operationsnamen korrigieren
401	UNAUTHENTICATED	Kein API-Schlüssel gesendet (Gastprojekt: Freigabe-Token fehlt oder ist falsch)	Authorization: Bearer mck_… senden
401	API_KEY_INVALID	Unbekannter, widerrufener oder gelöschter Schlüssel	Neuen Schlüssel erstellen
401	API_KEY_EXPIRED	Das Ablaufdatum des Schlüssels ist überschritten	Neuen Schlüssel erstellen
401	ACTOR_TOKEN_INVALID	Fehlerhaftes X-Actor-Token	Token über /runtime/actors anfordern oder den Header weglassen
403	API_KEY_SCOPE_INSUFFICIENT	Reiner Management-Schlüssel	Runtime- oder Full-Schlüssel verwenden
404	PROJECT_NOT_FOUND	Unbekannter Slug oder ein Projekt, zu dem der Schlüssel nicht gehört (bei /runtime/actors: das Projekt des Schlüssels wurde gelöscht)	Slug prüfen; Schlüssel dieses Projekts verwenden
429	TOO_MANY_REQUESTS	IP-Ratenlimit oder Tarifkontingent erreicht	Warten, dann erneut versuchen
429	MAX_ACTIVE_ACTORS_REACHED	Alle Actor-Plätze des Schlüssels sind belegt	Retry-After abwarten
429	RATE_LIMIT_EXCEEDED	Zu viele Actor-Token-Anfragen für einen Schlüssel (POST /runtime/actors)	Retry-After abwarten; ein aktives Token weiterverwenden
503	QUERY_TIMEOUT	Die Abfrage lief zu lange	Erneut versuchen; Abfrage eingrenzen

Fehlerantwort-Format

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

Ein 429 mit Retry-After-Header enthält zusätzlich retryAfter (Sekunden) im Body. Eine bediente Anfrage antwortet mit 200 und einem GraphQL-Body; Probleme auf Datenebene stehen in errors[] — zum Beispiel bedeutet extensions.code NOT_READY, dass die Tabelle noch nicht mit Daten verknüpft ist.

Beobachtbarkeit und Diagnose

Verfolge diese Kernsignale über Umgebungen hinweg, um die Integrationszuverlässigkeit aufrechtzuerhalten:

Wichtige Metriken

• Abfragestabilität — sind Antworten konsistent strukturiert? Achte auf unerwartete Schemaänderungen.
• Antwortform-Drift — ändern sich Feldtypen oder Verschachtelungsebenen zwischen Modell-Updates?
• Relations-Lookup-Zuverlässigkeit — werden verschachtelte Abfragen konsistent korrekt aufgelöst?
• Fehler- und Timeout-Muster — sind bestimmte Abfragen konsistent langsam oder fehlerhaft?
• Ratenlimit-Nähe — wie nah bist Du daran, Anfrage- oder Parallelitätslimits zu erreichen?

Überwachungsempfehlungen

• Alle API-Antworten (oder zumindest Statuscodes und Antwortzeiten) in Deiner Konsumentenanwendung loggen.
• Alarme für HTTP-429- und 401-Antworten einrichten — diese deuten auf Konfigurations- oder Kapazitätsprobleme hin.
• Antwort-Schemas periodisch gegen eine Baseline vergleichen, um unbeabsichtigten Drift zu erkennen.
• Actor-Token-Erneuerungsmuster überwachen, um Deine Parallelitätsstrategie zu optimieren.

int-03-observabilityMissing

Beobachtbarkeits-Checkpoints für Integrationszuverlässigkeit.

Best Practice

Developer / Integrator

Behandeln Du Mockomat-Artefakte als Contract-First-Assets. Halte Modellabsicht, Runtime-Verhalten und Implementierungsentscheidungen im selben Changeset nachvollziehbar. Wenn Dein Frontend von einer bestimmten Abfrageform abhängt, dokumentiere diese Abhängigkeit und validiere sie in CI.

Enterprise-Integrationshinweis

Enterprise User

Verwende für Enterprise-Umgebungen separate API-Schlüssel pro Umgebung (Entwicklung, Staging, Produktion). So kannst Du Nutzung pro Umgebung verfolgen und Schlüssel unabhängig rotieren. Kombiniere dies mit Actor-Tokens, um genau zu kontrollieren, wie viele gleichzeitige Konsumenten jede Umgebung unterstützt.