Client Integration

Mock Alpha has no SDK requirement. Integration is plain HTTP, so it works from any platform — Android, iOS, Flutter, web, desktop, scripts. This page describes the protocol; see Platform Examples for ready-to-paste code.

The two endpoints

Everything is built on two API routes:

{BASE} is your Mock Alpha instance URL, e.g. https://mock-alpha.your-domain.com.

Both require the project API key in a header:

X-Api-Key: <your-api-key>

Serving mocks

Send your normal API request with the path appended to /api/mock:

GET {BASE}/api/mock/users/123
X-Api-Key: <your-api-key>

Mock Alpha matches the path against the project's endpoints (path parameters like /users/{id} are normalised automatically), evaluates match rules, resolves response templates, and returns the active scenario's status code, headers, and body.

Force a specific scenario per request with a header or query parameter:

X-Mock-Scenario: error-404

GET {BASE}/api/mock/users/123?_scenario=error-404

Capturing endpoints

POST {BASE}/api/collect with this payload:

{
  "method": "GET",
  "path": "/users/123",
  "statusCode": 200,
  "responseBody": { "id": "123", "name": "Alex" },
  "serviceName": "my-app"
}

You can call /api/collect from anywhere: an interceptor in your app, a curl script, a Postman collection runner, or a CI job that replays a HAR file.

Integration patterns

Pattern 1 — direct base URL (simplest)

Point your app's API base URL at {BASE}/api/mock in dev builds and attach the X-Api-Key header. Seed endpoints manually via /api/collect or create them in the dashboard.

• ✅ Zero platform-specific code — works everywhere
• ❌ Endpoints must be seeded manually

Pattern 2 — capture-and-mock interceptor

In debug builds, an interceptor wraps every request:

App Request
    │
    ├── [real] → Backend API → real response → POST /api/collect  (capture)
    │
    └── [mock] → {BASE}/api/mock/<path> → scenario response → App

1. Forward the request to the real backend and capture the response
2. Report it to /api/collect (fire-and-forget — failures must never crash the app)
3. Request {BASE}/api/mock/<path> and return that response to the app

• ✅ Endpoints appear automatically as you navigate the app
• ✅ Real responses seed realistic default scenarios
• ❌ Requires a small amount of platform code (see examples)

Pattern 3 — capture only

Report traffic to /api/collect (e.g., from a staging proxy or test suite) without serving mocks, so the team can curate scenarios first. Flip to Pattern 1 or 2 when ready.

Choosing the base URL

With a deployed instance the whole table collapses to one HTTPS URL — this is the recommended setup for teams.

Guidelines

• Gate on debug builds. Never ship the interceptor or mock base URL in production builds.
• Make capture fire-and-forget. Reporting failures must not affect the user-facing request.
• Fall back to the real response. If Mock Alpha is unreachable, serve the real backend response instead of erroring.
• Set a distinct serviceName per app/module so the dashboard stays organised when multiple clients share a project.