Guide · Proxy and faults
AvailableMock the behavior under development, proxy the rest
Proxy mode lets a REST workspace sit in front of a real backend. Defined operations are mocked by default, unknown operations are forwarded, and endpoint overrides make exceptions explicit.
In this guide
- Migrate clients to mocks incrementally
- Keep stable backend behavior live
- Override routing per endpoint
- Understand dry-run and failure behavior
Prerequisites
- A DotMock workspace you can access
- The API ID in $API_ID and its published runtime URL in $MOCK_URL when the example calls the mock
On this page
Understand the routing decision
When proxy mode is enabled with a target URL, an explicit endpoint override wins first. Otherwise a path and method present in the REST definition are mocked; an unknown operation is proxied. GraphQL workspaces own one protocol endpoint and remain mocked by default.
explicit override → mock or proxy
defined REST operation → mock
unknown REST operation → proxySet one trusted upstream
Open API settings, enable proxy mode, and enter the upstream base URL. Then mark only the defined operations that should bypass the mock. DotMock appends the incoming path and query string to the target.
Know what is forwarded
The runtime preserves the HTTP method, request body, query string, and non-hop-by-hop headers, then adds standard forwarding headers. The upstream status, headers, and body become the mock response when proxying succeeds.
Make proxy failure explicit in tests
If the upstream call fails, the runtime falls back to normal mock evaluation. Define a meaningful fallback response for an explicitly proxied operation instead of relying on an accidental default.
Dry-run never contacts the upstream
Safe previews disable proxying, delivery, callouts, and persistence. They prove the local matcher and renderer only. Send a live request when the test must verify the configured upstream path.