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 + Actor-Token (Business+) oder öffentlich (Free/Quick)

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.

Authentifizierungsmuster

Authentifizierungsanforderungen hängen von Deinem Tarif und Endpunkttyp ab.

Öffentliche Endpunkte (Quick und Free)

Öffentliche Endpunkte erfordern keine Authentifizierung. Jeder HTTP-Client kann Abfragen senden:

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

Öffentliche Endpunkte sind pro IP-Adresse ratenbegrenzt, um Missbrauch zu verhindern.

Private Endpunkte (Business und Enterprise)

Private Endpunkte erfordern zwei Authentifizierungs-Header:

Header	Wert	Zweck
Authorization	Bearer <API_KEY>	Identifiziert das Projekt und autorisiert den Zugriff
X-Actor-Token	<ACTOR_TOKEN>	Identifiziert den Konsumenten für Parallelitäts-Tracking

API-Schlüssel-Authentifizierung

API-Schlüssel werden pro Projekt im Mockomat-Workspace ausgestellt. Jeder Schlüssel:

• Ist auf ein einzelnes Projekt beschränkt
• Kann rotiert werden, ohne andere Schlüssel zu beeinflussen
• Hat eigene Parallelitäts- und Ratenlimits
• Kann jederzeit widerrufen werden

Actor-Token-Workflow

Actor-Tokens verwalten gleichzeitige API-Konsumenten. Der Workflow:

1. Token anfordern — rufe den Actor-Endpunkt mit Deinem API-Schlüssel auf:

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

Antwort:

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

2. Token verwenden — fügst Du es in alle nachfolgenden Runtime-Anfragen ein:

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. Token läuft ab — Actor-Tokens haben ein konfigurierbares Inaktivitäts-Timeout (Standard 15 Minuten). Jede Anfrage verlängert das Timeout. Wenn das Token abläuft, fordern Du ein neues an.

int-01-authenticationMissing

Integrations-Einstieg mit Authentifizierung und Kontext-Setup.

Abfragemuster

Einfache Listenabfrage

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Detailabfrage

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

Gefilterte Abfrage

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

Sortierte und paginierte Abfrage

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

Verschachtelte Relationsabfrage

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

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 Frontend-Anwendung, Testsuite oder andere Konsumenten mit dem Mock-Endpunkt. Verwende Umgebungsvariablen oder Konfigurationsdateien, um zwischen Mockomat-Endpunkten und echten Backends zu wechseln:

// environment.ts
export const environment = {
  apiUrl: 'https://api.mockomat.com/mock/my-project/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: Validate schema contract
    run: |
      # Aktuelles Schema abrufen und mit Baseline vergleichen
      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

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

Mockomat wendet Ratenbegrenzung auf mehreren Ebenen an, um faire Nutzung und Plattformstabilität sicherzustellen.

Bereich	Free/Quick	Business	Enterprise
Pro IP	60 Anf./Min.	N/A	N/A
Pro API-Schlüssel	N/A	Tarifbasiert	Individuell
Pro Mandant	N/A	N/A	Konfigurierbar

Bei Ratenbegrenzung gibt die API HTTP 429 (Too Many Requests) mit einem Retry-After-Header zurück, der angibt, wie lange vor einem erneuten Versuch gewartet werden soll.

Fehlerbehandlung

Häufige Fehlerantworten und deren Behandlung:

HTTP-Status	Fehlercode	Bedeutung	Aktion
400	INVALID_QUERY	GraphQL-Abfrage-Syntaxfehler	Abfragesyntax prüfen
401	UNAUTHORIZED	Fehlender oder ungültiger API-Schlüssel	API-Schlüssel-Header verifizieren
401	SESSION_EXPIRED	Actor-Token ist abgelaufen	Neues Actor-Token anfordern
403	MAX_TENANT_SESSIONS_REACHED	Gleichzeitiges Sitzungslimit erreicht	Warten, bis eine Sitzung abläuft, oder eine freigeben
404	PROJECT_NOT_FOUND	Ungültiger Projekt-Slug	Endpunkt-URL verifizieren
429	RATE_LIMITED	Zu viele Anfragen	Für die Retry-After-Dauer warten
429	MAX_ACTIVE_ACTORS_REACHED	Gleichzeitiges Actor-Limit erreicht	Warten, bis ein Actor abläuft

Fehlerantwort-Format

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

Prüfe immer das Feld retryAfterSeconds, wenn verfügbar — es gibt Dir die Mindestwartezeit vor einem erneuten Versuch an.

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.