How It Works

Mimikos is a pipeline, not a black box. Understanding the pipeline helps you trust the output and debug unexpected responses.

The pipeline

Startup (once):
  OpenAPI Spec → Parser → Classifier → Behavior Map

Runtime (per request):
  Request → Router → Validator → Scenario Selection → Data Generator → Response Validator → Response
                       │
                       └──► Error Responder (for invalid requests)

Startup: spec → behavior map

When you run mimikos start, the spec is processed once:

1. Parser reads your OpenAPI spec (3.0 or 3.1, YAML or JSON), resolves $ref references, and extracts every operation with its request and response schemas

2. Classifier figures out what each endpoint does — list, fetch, create, update, delete — using the HTTP method, path pattern, and response schema. Endpoints that don’t match a clear pattern are classified as generic

3. Behavior Map stores the result: each endpoint paired with its classification, schemas, success codes, and examples. This map is built once and doesn’t change at runtime

The startup banner shows you the result — every endpoint, its classification, and any warnings about schemas that couldn’t be compiled.

Runtime: request → response

Each incoming request flows through:

1. Router matches the request to the right endpoint in the behavior map

2. Validator checks the request against the operation’s request schema — content type, required fields, type constraints. Invalid requests get an RFC 7807 error with field-level diagnostics

3. Scenario Selection picks the response status code and schema. By default, returns the success response. The X-Mimikos-Status header selects a specific status code instead

4. Data Generator walks the response schema and generates a value for each field using the priority chain: const → enum → example → semantic mapper → faker. The request fingerprint seeds the generation for determinism

5. Response Validator checks the generated response against the response schema. In default mode, logs a warning on failure. In strict mode, returns 500

Behavioral classification

Mimikos figures out what each endpoint does — without you telling it.

Behavior	Typical pattern	Stateful mode behavior
list	GET /resources	Returns stored resources
fetch	GET /resources/{id}	Returns stored resource or 404
create	POST /resources	Stores and returns new resource
update	PUT/PATCH /resources/{id}	Merges and returns updated resource
delete	DELETE /resources/{id}	Removes resource
generic	Anything ambiguous	Falls through to deterministic generation

Endpoints classified as generic still return valid schema-based responses — they just don’t participate in CRUD state management.

Response generation

The data generator produces realistic values by recognizing field names:

• email → alice.johnson@example.com
• firstName → Lori
• price → 42.99
• createdAt → 2024-08-15T10:30:00Z

120+ field patterns are mapped to contextually appropriate values. Field matching is case-insensitive and ignores separators (snake_case, camelCase, kebab-case all work).

For fields without semantic matches, the generator satisfies schema constraints: correct type, within min/max bounds, matching format, respecting enums. See Deterministic Mode for the full priority chain and how spec-authored examples take precedence.

Determinism

Every response is deterministic. The seed is derived from the request’s HTTP method, path, sorted query parameters, and body. The same combination always produces the same response — across restarts, across machines.

Each field is sub-seeded independently — the seed is derived from the request seed combined with the field’s path in the schema — so adding or removing a schema field doesn’t change existing field values.

Graceful degradation

Mimikos is designed to handle imperfect specs without crashing:

• Endpoints that fail during startup are skipped — the server starts with the remaining endpoints. If you request a failed endpoint, you get a 500 response in RFC 7807 format that includes the specific error, so you know what to fix in your spec
• Schemas that fail to compile produce a 500 response with the compilation error when you hit that endpoint. The error message tells you exactly which schema construct caused the failure
• Media-type examples bypass degraded schemas — if the spec defines an example, it’s served even when the schema is broken
• Request schema failures in non-strict mode are tolerated — the endpoint works but skips request validation

The startup banner tells you when degradation has occurred. Look for warnings like:

⚠ 2 endpoint(s) failed to register:
    POST /broken-endpoint
    GET /other-broken

⚠ 3 endpoint(s) have degraded schemas:
    POST /some-endpoint
    ...

If you see these, the server is running but the listed endpoints are affected. See Troubleshooting for what to expect when you hit a degraded endpoint and how to fix the underlying spec issues.