Create Mock Server and Manage Routes

Beeceptor is a robust mock server that empowers you to create mock APIs with zero coding required. This no-code solution enables you to deploy a dedicated sub-domain to serve as your API or server endpoint.

Creating a mocking rule

To manage mock server routes, use the Mocking Rules link on the endpoint's dashboard. Creating a rule involves two steps.

Mock rule - matching conditions

A request is matched against the HTTP method and a matching criteria. The matching criteria can be any of the following cases from the incoming request.

1. Request path exactly matches given text
2. Request path starts with given text
3. Request path contains given text
4. Request path matches a regular expression
5. Request body contains some text
6. Request body matches a regular expression
7. Request header value matches a regular expression

When a request is received at the Beeceptor endpoint, it's matched against the mocking rules. The first matched rule determines the mock response sent to the caller. You can adjust the priority of these rules by rearranging them in the list.

Generating a desired response

The second section in the create rule form defines what to send as HTTP response when the given rule is matched. You can define following things in this section.

1. Response HTTP status code: Enter a valid HTTP status code between 200 and 599.
2. Response Headers: Specify multiple response headers in JSON format.
3. Response Body/Payload: Define the content for the response.

When configuring a mocking rule within Beeceptor, you're presented with two options: Single Response and Weighted Response. This choice allows you to precisely define how your mock rule will handle incoming requests.

Single response

Single Response is straightforward; you specify a single response, including the status code, response payload, and HTTP headers, to be returned consistently for all incoming requests.

.

Weighted response

Weighted Response introduces a dynamic element. In this mode, you have the flexibility to declare multiple responses, each with its own set of parameters (status code, response payload, and HTTP headers). What's unique is that Beeceptor randomly selects one of these responses based on defined weights.

• For each additional response, you can assign a name and specify a weight in terms of percentage probability.
• You must have at least one response defined.
• The sum of all response weights must precisely equal 100%.
• The selection of responses is entirely random. While it will closely approximate the defined weights, it may not be exact in every instance.

Use case

Suppose you want to create a mock rule where there's a 1% chance of failure and a 99% chance of a successful response for incoming calls. You can set this up in the Weighted Response configuration as shown below:

Introducing delay

In the response section, you have the option to introduce a delay for the response. The caller will receive the response after a specific number of seconds.

tip

Beeceptor handles this delay computation on the server and attempts to match the specified seconds. However, please be aware that requests may take slightly longer than the exact time specified. This variance is influenced by factors such as network latency, server load, and other related variables.

Advance matching parameters

Here are a couple of advanced strategies to optimize request matching features within Beeceptor:

Multiple condition matching

Imagine a scenario where you are building a POST request at the endpoint /login and you want to simulate success and failure scenarios.

• If the entering request body contains the word 'alex' as a username the call should success with 200 OK.
• Else, the call should be failed with 401 Unauthorized.

With Beeceptor, you can craft a condition that triggers a successful login response specifically for Alex. Anyone else will fail the login attempt. This flexibility empowers you to simulate diverse scenarios, enhancing your testing and development workflow.

You can introduce AND conditions to incorporate supplementary conditions during the request matching process. Here's a brief demonstration showcasing this functionality in action.

Beeceptor provides a pre-built JSON Mock Server for the above login behavior. You should give it a try.

Matching path parameters

If you are matching a request using regular expression (RegEx) on the request path, you can use named groups. All the named groups and their values are available as template variables.

The above example considers that you are building an API mock for Company entity. You can match all the requests paths for Company entity and extract the company-id as path parameter.

Regular expression examples

• /companies/(?<company_id>[a-zA-Z0-9-]+) - for matching alphanumeric company-ids. Example request path /companies/be32a3a3-c2af-493c-adbd-ae2d09d8a0b8
• /companies/(?<company_id>[0-9]+) - for matching numeric company-ids. Example request path /companies/123

Using path parameters in templates

The named groups are available to be used as path parameters in templated response. You should use the following syntax.

{{pathParam 'group-name' 'default-value'}}

Example:

{{pathParam 'company_id' '123'}}

Find which rule matched

When dealing with multiple rules that share similar or slightly varied request paths, it can be challenging to pinpoint which rule was matched. Beeceptor simplifies this process by helping you identify the exact rule that matched.

Dashboard visibility

When a rule is successfully matched for a mocked response, a tickmark icon will appear alongside the request log on the dashboard. A single click allows you to review the specific rule that produced this match. To illustrate this feature, here's a quick demo.

Programmatic insight

For those who programmatically utilize Beeceptor APIs to configure mock rules, you can find an HTTP header named x-beeceptor-rule-id within the mocked response. This header contains the rule ID that was matched to generate the HTTP response, providing you with invaluable insights for debugging and troubleshooting.

Understanding execution order

In Beeceptor, the process of matching mock rules to incoming requests is key to generating mock responses. Here's how it works:

1. Request Matching: When a request is made to your Beeceptor endpoint, it is checked against the rules you've set up.
2. Rule Evaluation: Beeceptor evaluates these rules one by one until it finds the first rule that matches the incoming request.
3. Rule Matched: After Beeceptor identifies a matching rule, it proceeds to generate a mocked response.
   • Templated Response: If the rule specifies a templated response, Beeceptor prepares the response according to the template defined in the rule.
   • Response Delay: When a rule suggests a delay, Beeceptor ensures that the response content is delivered after the specified delay period.
4. Local Tunnel: (Optional) If the Local Tunnel feature is enabled, any incoming request that doesn't match your configured rules is automatically routed to your local machine's port. The response to this request is generated by your local service and returned to the caller. It's important to note that the localhost service should respond within a time frame of 60 seconds.
5. HTTP Proxy: (Optional) If you've set up an HTTP Proxy configuration for your Beeceptor endpoint, incoming requests are directed to an upstream API, typically an external HTTP endpoint. The response from this upstream service is then relayed back to the requester.
6. OpenAPI Specification: (Optional) If the Beeceptor endpoint is OAS enabled, incoming requests have their paths matched against the defined OpenAPI specification. Beeceptor generates mock responses based on the provided sample data or schema in the specification. This ensures that your API responses align with the structure and data defined in your OpenAPI documentation, making it easier to test your API against your documented contract.
7. No Matching Rule: In the event that none of the defined rules match the incoming request, Beeceptor automatically sends a default response with a 200 OK status code.

These capabilities make Beeceptor a flexible tool for crafting mock APIs that closely mimic the behavior you want.