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 the Mock Alpha instance URL: https://mock-alpha.duckdns.org.

Shorter mock URLs: mocks are also served on {BASE}/api/<path> directly (without the /mock segment), unless the first path segment collides with an internal prefix (auth, collect, invitations, mock, projects). /api/mock/<path> always works.

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.

API key rotation

Each project has one API key. To rotate it:

1. Go to Project Settings
2. Click Regenerate API Key
3. Update the key wherever your clients store it (e.g., Android local.properties, web .env, CI secrets)

Old requests using the previous key will be rejected immediately.

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.