Answer from a mock server

Give a project a public address that answers like your API, from its saved examples.

In short

A mock server is a public address that answers like your API, from the examples saved on a project's requests. Use it to build or test an app before the API is ready, or to see how your app copes when the API is slow or failing. Each project has one.

Before you start

• Who: only people who manage the project see the address and the key, and start, change or delete the mock. Starting one needs a confirmed email address.
• Plan: your plan sets how many mock calls a workspace gets each month (Mock server calls in Plan & usage).
• First: save at least one response as an example.

Steps

1. Save at least one response as an example: /help/api-testing/saved-examples.
2. Open "Build", choose "Mocks, streams & docs", choose the project and open "Mock server" - or choose "Mock server" in the project's … menu on Requests.
3. Press "Start the mock server". You need a confirmed email address.
4. Press "Copy address" and call it, or copy the ready curl command under it.

Result: the mock answers calls that match a saved request with an example. To see one working in two minutes, press "Mock the sandbox bookstore".

How it answers

• The method and path of a call must match a saved request that has an example. A path segment written {{name}}, {name} or :name matches anything, and HEAD is answered as GET.
• When several requests match, the one with more of its path written out wins, then one whose fixed query values are all in the call.
• The caller can ask for one example by name or status.
• Otherwise an example whose conditions the call meets answers. Open an example and add conditions under "Answers when": a header, query value, path segment or body field (written like order.items.0.sku) that equals, does not equal, contains, is there or is missing. Every condition must hold, and the example with the most conditions wins - for example, answer 401 when the Authorization header is missing.
• Otherwise the default example answers. A credential header such as Authorization can only be checked for being there or missing, so no credential is kept in a condition.
• An example's body can answer with parts of the call: {{request.path.id}} (a segment the saved request writes as {{id}}, {id} or :id), {{request.query.page}}, {{request.header.X-Tenant}}, {{request.body.order.id}} (a field of a JSON body; numbers pick a list item, as in items.0.sku) and {{request.method}}. Fresh values: {{$uuid}}, {{$now}}, {{$timestamp}} and {{$randomInt}} (0 to 1,000).
• In a JSON body a filled-in value is escaped so the answer stays valid JSON. Credential headers, cookies and the mock key are never echoed, and anything the call does not have stays as written.

Latency, errors and a key

• "Simulated latency" makes every answer wait, up to 5,000 ms.
• "Error rate" answers that share of calls with the error status you choose, from 400 to 599, instead of an example. Press "Save" to apply.
• "Require a key": callers must send the key in the X-Mock-Key header. A call without it is refused and logged as Key refused. "New key" replaces the key at once.

A mock that remembers calls

Switch on "Remember what calls send" to let your app create, change and delete data on the mock, as it would on the real API.

• POST a JSON object to a list address, such as /books. The mock keeps it under its "id", or gives it a new id, and answers 201 with the record.
• GET /books lists every record. GET, PUT, PATCH and DELETE on /books/42 read, replace, change or delete that one.
• While a list holds nothing, the mock answers with your examples, as before. Each method still needs a saved request with an example, so the mock knows the address.
• To get an example anyway, send X-Mock-Example or X-Mock-Status, or add ?__example= or ?__status= to the address.
• Password, token and other secret fields are masked before they are kept. A record can be at most 16 KB, and a mock keeps at most 500 records. Each is deleted 7 days after it was last written.
• "Forget records" deletes everything callers sent. Switching remembering off deletes it too.

Forward other calls and record the answers

Under "Forward other calls", give the address of your real API, such as https://api.example.com. A call nothing in the mock answers - no saved request matches it, or the request has no example that fits - then goes to that address, below its path, and its answer comes back.

• The mock forwards only to a site your workspace proved it owns (Settings › Site ownership). The proof is asked again on every call; once it lapses, calls answer 502 with the code mock_proxy_not_proved.
• Cookies, credentials, the mock key and the caller's address are never passed on. Only content headers, such as Accept, and the caller's own X- headers go along.
• The answer must come within 20 seconds as text of at most 256 KB. HTML and scripts come back as plain text, like an example. A forwarded answer carries X-Mock-Source: proxy.
• Switch on "Keep what comes back as drafts" to record each answer, one per method and path, with passwords, tokens and your project's secret values masked. A mock keeps at most 50 drafts, each for 14 days.
• "Recorded answers" lists the drafts. Someone who can edit the project opens one and presses "Keep as example": it joins the request the call matched, or a new request on {{baseUrl}} and that path. From then on the mock answers that call itself. "Dismiss" deletes a draft.
• The mock never serves a draft, and every forwarded call counts like any other mock call.

The request log

"Request log" lists the newest calls first: method, path, status, how each was answered - Answered, No match, Simulated error, Key refused, Forwarded or Not forwarded - and when. Click a call for its headers and body, shown as text only. Credentials are masked. The log keeps the newest 200 calls for 3 days.

Good to know

• Only people who manage the project see the address and the key. Anyone who has the address can call it, so share it on purpose.
• Switch the mock off to stop it answering without losing anything. "New address" stops the old one at once. "Delete mock" removes the address and its log; the examples stay.
• A caller whose call matches nothing is not told what exists.
• A mock never serves HTML or scripts as a page (they are plain text), never sends cookies, and never redirects to other sites.
• A mock answers a set number of calls a minute; your plan sets how many mock calls a workspace gets each month (Mock server calls in Plan and usage).
• If a mock address is used to deceive or harm someone, anyone can report it at /report-abuse. Moderators can take a mock down.

If something goes wrong

• A call is logged as "No match": no saved request with an example matches its method and path.
• The mock stopped answering: the workspace is frozen or read-only, its plan leaves API Tester out, the monthly mock calls are used up, or moderators took it down.
• "Start the mock server" is refused: confirm your email address first.
• "This mock remembers JSON objects only": send a JSON object as the body, not a list or plain text.
• "... is already in ..." (409): a record with that id exists. Use PUT on its address to replace it.
• "Nothing is remembered as ..." (404): the list has records, but not that one.
• "This mock remembers at most 500 records" (507): press "Forget records", or delete some.

Related

• /help/api-testing/saved-examples
• /help/api-testing/published-api-pages
• /help/api-testing/quality-view