Skip to main content

Mock Rules & Request Matching

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 mock rule​

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

creating a mocking rule

Matching requests​

When a request arrives at the Beeceptor endpoint, it is evaluated against the mock rules. The first rule that matches the request is selected, and the corresponding mock response is sent back to the client. You have the flexibility to modify the order of these rules and set priority.

Matching with request parameters​

A mock rule can be defined using one or more of the following matching criteria:

  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

adding match conditions in mock rule

Adding multiple conditions in a mock rule.

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

Multiple conditions using AND​

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.

mock rule with multiple conditions

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

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.

path parameter match using regular expression

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'}}

Matching with state data​

Beeceptor is a stateful mock server, allowing you to save, update, and share state data across multiple requests. This enables you to design context-aware responses that reflect real-world API behavior. You can also combine state-based filters with standard request filters to build rules that respond dynamically based on previously stored values or counters.

adding-state-filters-in-mock-rules

Beeceptor supports three types of state variables:

  • Datastore (key–value pairs),
  • List, and
  • Counter.

The type Datastore (key–value pairs) is ideal for storing simple attributes, such as user preferences or feature flags. For a deeper dive into using state variables inside response templates refer to this comprehensive guide.

Generating a 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 mock 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.

single-response.

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:

define weights for responses, random pick

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.

mocking-rule-delay-in-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.

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.

highlight the matched mock rule in Beeceptor

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.