Integrators

This section is for developers connecting Mockomat workflows into broader engineering systems. Whether you are building a frontend that consumes a Mockomat mock API, automating model validation in CI/CD, or integrating Mockomat into your team's development pipeline, this page covers the patterns and practices you need.

API Endpoints Overview

Mockomat exposes two distinct API surfaces:

API	Endpoint	Purpose	Authentication
Management API	GET /graphql	Project CRUD, model configuration, user management	JWT (session-based)
Mock Runtime API	POST /mock/{slug}/graphql	Query mock data, test domain behavior	API key + Actor Token (Business+) or public (Free/Quick)

The management API is used by the Mockomat web application and administrative tooling. The mock runtime API is what your applications consume as a mock backend.

Authentication Patterns

Authentication requirements depend on your plan and endpoint type.

Public Endpoints (Quick and Free)

Public endpoints require no authentication. Any HTTP client can send queries:

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

Public endpoints are rate-limited per IP address to prevent abuse.

Private Endpoints (Business and Enterprise)

Private endpoints require two authentication headers:

Header	Value	Purpose
Authorization	Bearer <API_KEY>	Identifies the project and authorizes access
X-Actor-Token	<ACTOR_TOKEN>	Identifies the consumer for concurrency tracking

API Key Authentication

API keys are issued per project in the Mockomat workspace. Each key:

• Is scoped to a single project
• Can be rotated without affecting other keys
• Has its own concurrency and rate limits
• Can be revoked at any time

Actor Token Workflow

Actor tokens manage concurrent API consumers. The workflow:

1. Request a token — call the actor endpoint with your API key:

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

Response:

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

2. Use the token — include it in all subsequent runtime requests:

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 expires — actor tokens have a configurable idle timeout (default 15 minutes). Each request refreshes the timeout. If the token expires, request a new one.

int-01-authenticationMissing

Integration entry with auth and context setup.

Query Patterns

Basic List Query

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

Detail Query

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

Filtered Query

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

Sorted and Paginated Query

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

Nested Relation Query

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

Recommended Integration Flow

1. Define a Stable Domain Scope

Before integrating, identify which entities and queries your application will consume. Do not integrate against a model that is still changing frequently — wait until the core structure is stable.

2. Lock Naming and Field Contracts

Treat the GraphQL schema as a contract. Once your application depends on specific query names and field structures, changes to those names will break the integration. Use the API design view in Mockomat to finalize query names before connecting consumers.

3. Validate Runtime Behavior

Run comprehensive queries through the runtime preview and verify:

• Field types match what your application expects
• Relation nesting works correctly
• Filters return the expected subsets
• Pagination produces clean page boundaries

4. Integrate Consumer Systems

Connect your frontend application, test suite, or other consumers to the mock endpoint. Use environment variables or configuration files to switch between Mockomat endpoints and real backends:

// environment.ts
export const environment = {
  apiUrl: 'https://api.mockomat.com/mock/my-project/graphql',
  // Switch to real backend when ready:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Promote to Export/Implementation

When the mock API contract is stable and your frontend is working correctly against it, use the Export feature to generate a production backend that implements the same contract.

int-02-ci-cd-flowMissing

CI/CD integration pattern with model and runtime gates.

CI/CD and Automation

Mockomat mock APIs can be integrated into your CI/CD pipeline to validate frontend behavior against a stable mock backend.

Pipeline Integration Patterns

Contract validation — run schema comparison checks when models change to detect breaking changes before they reach consumers.

Integration tests — point your integration test suite at the Mockomat endpoint to verify frontend behavior against realistic mock data.

Preview validation — before merging model changes, validate that the runtime produces expected results by querying the preview endpoint programmatically.

Example Pipeline Steps

# Example CI pipeline step
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: |
      # Fetch current schema and compare to 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

Versioning Generated Artifacts

When using the export feature, version the generated backend code alongside your application:

• Commit generated code to a dedicated branch or repository.
• Tag exports with the model version or date.
• Include a changelog summarizing model changes since the last export.
• Review generated code diffs before merging into main.

Rate Limiting

Mockomat applies rate limiting at multiple levels to ensure fair usage and platform stability.

Scope	Free/Quick	Business	Enterprise
Per IP	60 req/min	N/A	N/A
Per API key	N/A	Based on plan	Custom
Per tenant	N/A	N/A	Configurable

When rate-limited, the API returns HTTP 429 (Too Many Requests) with a Retry-After header indicating how long to wait before retrying.

Error Handling

Common error responses and how to handle them:

HTTP Status	Error Code	Meaning	Action
400	INVALID_QUERY	GraphQL query syntax error	Check query syntax
401	UNAUTHORIZED	Missing or invalid API key	Verify API key header
401	SESSION_EXPIRED	Actor token has expired	Request a new actor token
403	MAX_TENANT_SESSIONS_REACHED	Concurrent session limit hit	Wait for a session to expire or release one
404	PROJECT_NOT_FOUND	Invalid project slug	Verify the endpoint URL
429	RATE_LIMITED	Too many requests	Wait for Retry-After duration
429	MAX_ACTIVE_ACTORS_REACHED	Concurrent actor limit hit	Wait for an actor to expire

Error Response Format

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

Always check the retryAfterSeconds field when available — it tells you the minimum wait time before retrying.

Observability and Diagnostics

Track these core signals across environments to maintain integration reliability:

Key Metrics

• Query stability — are responses consistently structured? Watch for unexpected schema changes.
• Response shape drift — are field types or nesting levels changing between model updates?
• Relation lookup reliability — do nested queries consistently resolve correctly?
• Error and timeout patterns — are certain queries consistently slow or failing?
• Rate limit proximity — how close are you to hitting request or concurrency limits?

Monitoring Recommendations

• Log all API responses (or at least status codes and response times) in your consumer application.
• Set up alerts for HTTP 429 and 401 responses — these indicate configuration or capacity issues.
• Compare response schemas periodically against a baseline to detect unintended drift.
• Monitor actor token refresh patterns to optimize your concurrency strategy.

int-03-observabilityMissing

Observability checkpoints for integration reliability.

Best practice

Developer / Integrator

Treat Mockomat artifacts as contract-first assets. Keep model intent, runtime behavior, and implementation decisions traceable in the same change set. When your frontend depends on a specific query shape, document that dependency and validate it in CI.

Enterprise integration note

Enterprise User

For enterprise environments, use separate API keys per environment (development, staging, production). This lets you track usage per environment and rotate keys independently. Combine with actor tokens to control exactly how many concurrent consumers each environment supports.