Proxy and record

With proxy passthrough, the mock stands in front of a real API. Your endpoints answer the requests they match, and everything else is forwarded to the real server and its reply passed back. With recording on, you can turn those real replies into mock endpoints with one click.

When to use it

• Mock one part of an API. Point your app at the mock, write endpoints for the routes that are missing or that you want to control, and let the rest reach the real API.
• Force an error on one route. Add an endpoint that returns 500 for /payments, and leave every other route real.
• Build a mock from real traffic. Use the app normally through the proxy, then save the recorded replies as endpoints. Afterwards the app can run with no real API at all.

Turn on passthrough

1. Select Project in the rail.

2. Under Proxy passthrough, type the real API's address in Forward unmatched requests to (base URL), for example https://api.example.com.

3. Start the server, and point your app at the mock's address, such as http://localhost:8080.

Now a request to the mock goes one of two ways:

The request	What happens
Matches an enabled endpoint	The endpoint answers, as usual.
Matches no endpoint	It is forwarded to the base URL with the same method, path, query string and body. The real reply is sent back to the client.

A call to http://localhost:8080/v1/users?page=2 is forwarded to https://api.example.com/v1/users?page=2.

Leave the field empty to turn passthrough off. Unmatched requests then get the mock's 404 again.

What is forwarded

• The method, path, query string and body are forwarded unchanged.
• Request headers are forwarded, including Authorization and cookies. The Host header and connection-level headers are set fresh for the real server.
• The real status code, headers and body come back to the client. When Enable CORS is on, the CORS headers are added.
• Global delay and global headers are not applied to proxied replies.

In the Live section a forwarded request carries a proxied tag. See Live request log.

If the real API cannot be reached

If the real server does not answer within 30 seconds, or the address is wrong, the mock answers 502 with this body:

{
  "error": "proxy_failed",
  "message": "…the reason…"
}

Record real replies

1. Under Proxy passthrough, set the base URL as above.

2. Turn on Record proxied responses.

3. Use your app, or send requests yourself, so that calls pass through the proxy.

4. Go back to Project. A panel lists the captured replies, headed with the count, such as 3 recorded responses. Each row shows the method, path and status.

5. Select Save as mock on a row.

Mock Studio creates an endpoint from the recording and removes the row from the panel. A message confirms it, for example Saved "GET /v1/users" as a mock endpoint. The new endpoint has:

Field	Value
Name	The method and path, such as GET /v1/users
Method and path	As recorded
Response label	The status and (recorded), such as 200 (recorded)
Status	As recorded
Body type	JSON when the real reply was JSON, otherwise Text
Body	The real reply's body

From then on the mock answers that route itself, and the request is no longer forwarded.

Select Clear to throw away the recordings you have not saved.

Tidy up a recorded endpoint

A recording is one exact request. After saving, edit the endpoint to make it general:

• Turn ids into parameters. A recording of /v1/users/42 only answers that one path. Change the path to /v1/users/:id and replace the id in the body with {{params.id}}. See Endpoints and paths.
• Remove real data. Replace names, emails and tokens from the real reply with made-up values or tokens such as {{faker.name}}. See Dynamic templating.
• Add the cases you could not record. Add error responses with conditional rules or a sequence.
• Add headers if they matter. A recording keeps the status and body. Response headers from the real API are not copied to the endpoint.

Limits

• The panel shows up to 20 recordings at a time. Up to 200 are held; beyond that the oldest are dropped.
• Recordings are kept in memory until you save them, press Clear or quit Mock Studio.
• Only requests that match no endpoint are forwarded, so only those are recorded.

WARNING

Proxying sends your app's real requests, with their credentials, to the address you set, and recording keeps real replies on screen and, once saved, in the project file. Record against a test or staging API where you can. Check saved endpoints for personal data and secrets before you commit the project to Git or share it. Do not leave passthrough on while a public tunnel is running unless you mean to expose the real API through it.

Stop proxying

Clear the Forward unmatched requests to (base URL) field. To keep the address but stop a particular route from reaching the real API, add an endpoint for that route.

Next steps

• Live request log
• Projects, files and Git
• Testing with mocks