Skip to content
Mockifyr

Proxying

A stub with proxyBaseUrl forwards the request to another service and returns that service’s response. Use it to stub part of an API while the rest still hits the real thing.

{
  "request": { "method": "GET", "urlPathPattern": "/api/.*" },
  "response": { "proxyBaseUrl": "https://api.example.com" }
}

Fields

FieldEffect
proxyBaseUrlThe target base URL
additionalProxyRequestHeadersHeaders added to the outbound request
proxyUrlPrefixToRemoveStrip this prefix from the path before forwarding

The proxy forwards the method, path, query string, body and headers — with the exception of Host, which is set for the target.

"response": {
  "proxyBaseUrl": "https://api.example.com",
  "proxyUrlPrefixToRemove": "/legacy",
  "additionalProxyRequestHeaders": { "X-Forwarded-By": "mockifyr" }
}

Environment substitution

Proxy targets are resolved through environments, so a {{key}} in proxyBaseUrl is substituted at serve time:

"response": { "proxyBaseUrl": "{{upstreamBaseUrl}}" }

That lets the same stub set point at a different backend per tenant without editing the mapping.

Proxying to a service on your host from a container

This is the failure most people hit first. A proxyBaseUrl of http://localhost:PORT inside a container resolves to the container’s own loopback, not your machine’s — so the service you meant to reach is not there.

Mockifyr handles this: a loopback target that refuses the connection is retried once against host.docker.internal. If that also fails, the response is a 502 Bad Gateway naming the cause rather than an opaque 500, so the journal tells you what happened instead of leaving you guessing.

Terminal window
# disable the retry — a refused loopback proxy then returns a plain 500
docker run -p 8080:8080 ghcr.io/omercelikdev/mockifyr --outbound-host-fallback false