Usage Patterns
These playbooks show how people use Counterfact in real development and test work. Start with the path that matches your situation, then follow the links as your API grows.
Most projects start with Explore a New API or Executable Spec to get a running server from an OpenAPI spec with no code. From there, Mock APIs with Dummy Data and AI-Assisted Implementation are the natural next steps for adding useful responses — the former by hand, the latter with an AI agent doing the heavy lifting. Model the Workflow, Not the Backend sets the boundary for both: prefer deterministic handlers and add only the state that a supported client workflow can observe.
As the mock grows, Scenario Scripts let you automate repetitive REPL interactions — seeding data on startup, building reusable request sequences — while Federated Context Files, Share State Across API Groups, and Test the Context, Not the Handlers keep stateful logic organized and reliable. Live Server Inspection with the REPL is Counterfact’s most distinctive feature, letting you seed data, send requests, and toggle behavior in real time without restarting, and Simulate Failures and Edge Cases and Simulate Realistic Latency extend any mock to cover the error paths and performance characteristics that real services exhibit.
When your project involves multiple versions or multiple specs, Multiple API Versions shows how to serve them from a shared set of route files using $.minVersion() to branch on version without duplicating handlers. For teams that want the mock to remain a reliable, long-lived artifact, Reference Implementation and Automated Integration Tests make it a first-class part of the codebase that can run in CI. Finally, Agentic Sandbox and Hybrid Proxy address the two common integration strategies — isolating an AI agent from the real service, or blending mock and live traffic — and Custom Middleware covers cross-cutting concerns like authentication and logging without touching individual handlers.
Find your path
| Pattern | When to use it |
|---|---|
| Explore a New API | You have a spec but no running backend or production access |
| Executable Spec | You want immediate feedback on how spec changes affect the running server during API design |
| Mock APIs with Dummy Data | You need realistic-looking responses to build a UI, run a demo, or write assertions |
| Model the Workflow, Not the Backend | A workflow needs shared state, but the simulator should remain small and deterministic |
| Scenario Scripts | You want to automate REPL interactions, seed data on startup, or build reusable state configurations |
| AI-Assisted Implementation | You want an AI agent to replace random responses with working handler logic |
| Federated Context Files | You want each domain to own its state, with explicit cross-domain dependencies |
| Share State Across API Groups | Several API groups model one product and need shared domain data or invariants |
| Test the Context, Not the Handlers | You want to keep shared stateful logic reliable as the mock grows |
| Live Server Inspection with the REPL | You want to seed data, send requests, and toggle behavior without restarting the server |
| Simulate Failures and Edge Cases | You need reproducible, on-demand error conditions for development or testing |
| Simulate Realistic Latency | You want to test how clients and UIs behave under realistic response times |
| Reference Implementation | You want a working, executable implementation that expresses intended API behavior in code |
| Multiple API Versions | You maintain multiple versions of an API and want shared handlers that adapt by version |
| Agentic Sandbox | You are building an AI coding agent and want to avoid rate limits and costs during development |
| Hybrid Proxy | Some endpoints exist in the real backend; others need to be mocked |
| Automated Integration Tests | You want to run real HTTP tests against the mock in a CI-friendly test suite |
| Custom Middleware | You want authentication, headers, or logging applied uniformly across a group of routes |