Manage Mocking Rules

Beeceptor's Rule Management APIs allows you to programmatically create or modify the mocking rules for an endpoint. This enables automated setup or update of rules to meet various testing scenarios. Any changes made are immediately reflected on the Beeceptor's endpoint (mock server).

Rule Selection

A Beeceptor endpoint can be configured with multiple mocking rules, allowing for a granular level of control over how requests are matched. These rules can differentiate requests based on the URL path or specific data within the request body. When a request is made to an endpoint, Beeceptor evaluates the mocking rules in the order they are displayed. The system then selects the first rule that meets the request's criteria to generate and deliver the appropriate mock response.

Get All Rules

List all rules configured for an endpoint.

Request Details

Method	Request Path
`GET`	`https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules`

<my-endpoint> - name of the Beeceptor endpoint

Response Object Details

Response holds an array of found requests in data parameter. Refer a sample below.

Response parameters	Details
`id`	identifier to uniquely identifies this rule.
`enabled`	Default - `true`. Helps you turn on/off a rule to skip evaluation.
`mock`	Default - `true`. When using proxy setup, this indicates if the rule should attempt mocking. E.g. when set to false `false` mocking is not attempted and only `delay` is effective.
`description`	Optional. Description of the rule
`delay`	Indicates if this rule should respond after these milliseconds
`match.method`	During rule evaluation, filter request with this method (GET, POST, PUT, etc). This will be applied as AND logic with `operator` parameter.
`match.operator`	Operator to match the incoming request. Possible values: `SW` - request path starts with `CO` - request path contains `EM` - request path exactly matches `REGEX` - request path/URL matches a regular expression `B_CO` - request body contains `B_REGEX` - request body matches a regular expression `H_REGEX` - request header value matches a regular expression
`match.value`	During rule evaluation, match the request path with this value. (`operator` is used to match against this value)
`sendType`	Possible values are `send` and `sendRandom`. The first case (`send`) is when mocking rule has a single fixed response. If this attribute is empty or not present, a fixed mocking response is picked for backward compatibility.
`send.status`	When the rule is matched, response HTTP status code to send.
`send.body`	When the rule is matched, response body to send.
`send.headers`	When the rule is matched, response headers to send.
`send.templated`	Optional. Enable HandlesBar templates in the mocked response. Defaults to false. Read more here
`sendRandom`	It is a list of `send` objects with percentage weights. When `sendType` is `sendRandom`, a response object from this attribute is picked. Refer the feature documentation here.

Success Response

A success response has 200 as HTTP status code.

{
  "data": [
    {
      "enabled": true,
      "mock": false,
      "delay": 10,
      "match": {
        "method": "GET",
        "operator": "SW",
        "value": "/abc"
      },
      "send": {
        "status": 200,
        "body": "{ \"status\": \"Awesome!\"}",
        "headers": {
          "Content-Type": "application/json",
          "a": "200"
        },
        "templated": false
      },
      "id": "dqio3ubf3wh",
      "description": "some description of this rule"
    },
    {
      "enabled": true,
      "mock": true,
      "delay": 10,
      "match": {
        "method": "PATCH",
        "operator": "EM",
        "value": "/xyz"
      },
      "send": {
        "status": 200,
        "body": "{ \"status\": \"Awesome!\"}",
        "headers": {
          "Content-Type": "application/json",
          "method": "put"
        },
        "templated": false
      },
      "id": "gl9dgq67mn9"
    },
    {
      "enabled": false,
      "mock": false,
      "delay": 10,
      "match": {
        "method": "GET",
        "operator": "SW",
        "value": "/omg"
      },
      "send": {
        "status": 200,
        "body": "{ \"status\": \"Awesome!\"}",
        "headers": {
          "Content-Type": "application/json",
          "a": "200"
        },
        "templated": false
      },
      "id": "2c8t3wwqcbv",
      "description": "matching omg requests"
    }
  ]
}

Get One Rule

Retrieve one rule based on rule's ID.

Request Details

Method	Request Path
`GET`	`https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules/<rule-id>`

<my-endpoint> - name of the Beeceptor endpoint
<rule-id> - id of the rule to retrieve

Response structure is same as get all rules.

Success Response

{
  "data": [
    {
      "enabled": true,
      "mock": true,
      "delay": 10,
      "match": {
        "method": "PATCH",
        "operator": "EM",
        "value": "/xyz"
      },
      "send": {
        "status": 200,
        "body": "{ \"status\": \"Awesome!\"}",
        "headers": {
          "Content-Type": "application/json",
          "method": "put"
        },
        "templated": false
      },
      "id": "gl9dgq67mn9"
    }
  ]
}

Error Response

When a rule is not found with given ID, 404 status code is returned.

{
  "error": {
    "code": "no_rule_found",
    "message": "Rule not found with given id"
  }
}

Create A Rule

Use this API to create a new mocking rule. The new rule will be inserted at the end of the rules list.

Endpoint

HTTP Method	Request Path
`POST`	`https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules/`

<my-endpoint> - name of the Beeceptor endpoint

Example: Create a rule to match request path starting with a prefix

In the example below, a rule is created where request path/URL starts with /my-api-path. Refer the table above (in GET section) for detailed description of request parameters.

{
    "enabled" : true,
    "mock" : true,
    "delay" : 0,
    "match" : {
        "method" : "GET",
        "value" : "/my-api-path",
        "operator" : "SW"
    },
    "send" : {
        "status" : 200,
        "body" : "{ \"status\": \"Awesome!\"}",
        "headers" : {
            "Content-Type": "application/json",
            "my-custom-header": "some-data"
        },
        "templated": false
    }
}

Success Response

The following represents a success response with 200 as HTTP response code. The created rule is present in data parameter and has id field to uniquely identify this rule.

{
  "data": {
    "enabled": true,
    "mock": true,
    "delay": 0,
    "match": {
        "method": "GET",
        "operator": "SW",
        "value": "/my-api-path"
    },
    "send": {
        "status": 200,
        "body": "{ \"status\": \"Awesome!\"}",
        "headers": {
            "Content-Type": "application/json",
            "my-custom-header": "some-data"
        },
        "templated": false
    },
    "id": "s6ocngast47"
  }
}

Error Response

For validation errors, the HTTP response code will be 400.

{
  "error": {
    "code": "bad_request",
    "message": "/delay: should be >= 0",
    "parameter": "/delay"
  }
}

When there is malformed JSON in the request body, the HTTP response code will be 400.

{
  "error": {
    "code": "invalid_json_body",
    "message": "Invaid JSON in request body"
  }
}

Example: Create a rule to match requests having specific HTTP header

The below example creates a rule to match requests having specific value in HTTP Header named x-custom-header.

{
    "match": {
        "method": "GET",
        "operator": "H_REGEX",
        "header": {
            "key": "x-custom-header",
            "value": ".+SOME_VALUE_IN_HEADER.+"
        },
        "value": ""
    },
    "delay": 0,
    "send": {
        "status": 299,
        "body": "{ \"status\": \"SOME_VALUE_IN_HEADER - Awesome!\"}",
        "headers": {
            "Content-Type": "application/json"
        },
        "templated": false
    },
    "mock": true,
    "enabled": true
}

Example: Create a rule that picks a random response based on weights

To create a rule that selects a random response based on weights, follow the example below. Notice the sendType is passed as sendRandom here.

This rule is designed to match requests with a request path of /random-responses. It randomly selects a response based on specified weights. For instance, in the following rule, the success response will be chosen for 90% of the requests and sends 200 OK HTTP status code, while approximately 10% of the requests will receive a failure response with a 501 HTTP status code.

{
    "match": {
        "method": "GET",
        "operator": "EM",
        "value": "/random-responses"
    },
    "delay": 0,
    "mock": true,
    "sendType": "sendRandom",
    "sendRandom": [
        {
            "weight": 90,
            "name": "Success 200",
            "delay": 0,
            "send": {
                "status": 200,
                "body": "{ \"status\": \"Success From Random Response!\"}",
                "headers": {
                    "Content-Type": "application/json"
                },
                "templated": false
            }
        },
        {
            "weight": 10,
            "name": "Failure 501",
            "delay": 0,
            "send": {
                "status": 501,
                "body": "{ \"status\": \"Failure From Random Response!\"}",
                "headers": {
                    "Content-Type": "application/json"
                },
                "templated": false
            }
        }
    ],
    "enabled": true
}

Read more details and feature documentation here.

Update A Rule

Use this API to update an existing mocking rule. Using this you can update the rule matching criteria and the response body and headers. Once the rule is updated, it may take a few seconds to get it reflected.

Endpoint

HTTP Method	Request Path
`PUT`	`https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules/<rule-id>`

<my-endpoint> - name of the Beeceptor endpoint
<rule-id> - ID of the rule (typically received in the GET call)

Request

Refer the table above (in GET section) for the description of parameters in the request body.

{
    "enabled" : true,
    "mock" : true,
    "delay" : 31000,
    "match" : {
        "method" : "POST",
        "value" : "/customers",
        "operator" : "SW"
    },
    "send" : {
        "status" : 200,
        "body" : "{ }",
        "headers" : {
          "Content-Type": "application/json",
          "my-custom-header": "some-data"
        },
        "templated": false
    }
}

Success Response

The following represents a success response with 200 as HTTP response code. The updated rule is present in data parameter and has id field same as in the URL.

{
  "data": {
    "enabled": true,
    "mock": true,
    "delay": 31000,
    "match": {
      "method": "POST",
      "operator": "SW",
      "value": "/customers"
    },
    "send": {
      "status": 200,
      "body": "{ }",
      "headers": {
        "Content-Type": "application/json",
        "my-custom-header": "some-data"
      },
      "templated": false
    },
    "id": "qo40pe5susb"
  }
}

Error Response

For validation errors, the HTTP response code will be 400. For example, the below response when 'body' parameter is missing in the request.

{
  "error": {
    "code": "bad_request",
    "message": "/send: should have required property 'body'",
    "parameter": "/send"
  }
}

Delete A Rule

Use this API to delete a rule or all the rules for this endpoint. Note that this call is non-recoverable.

Request Details

Method	Request Path
`DELETE`	`https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules`
`DELETE`	`https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules/<rule-id>`

<my-endpoint> - name of the Beeceptor endpoint.
<rule-id> - Optional. Id of the specific rule to delete. When rule-id is not passed, all rules will be deleted for this endpoint.

Success Response

In the response, rulesDeleted indicates number of rules deleted with this API call.

{
    "data": {
        "rulesDeleted": 1
    }
}

Get All Rules​

Request Details​

Response Object Details​

Success Response​

Get One Rule​

Request Details​

Success Response​

Error Response​

Create A Rule​

Endpoint​

Example: Create a rule to match request path starting with a prefix​

Success Response​

Error Response​

Example: Create a rule to match requests having specific HTTP header​

Example: Create a rule that picks a random response based on weights​

Update A Rule​

Endpoint​

Request​

Success Response​

Error Response​

Delete A Rule​

Request Details​

Success Response​

Get All Rules

Request Details

Response Object Details

Success Response

Get One Rule

Request Details

Success Response

Error Response

Create A Rule

Endpoint

Example: Create a rule to match request path starting with a prefix

Success Response

Error Response

Example: Create a rule to match requests having specific HTTP header

Example: Create a rule that picks a random response based on weights

Update A Rule

Endpoint

Request

Success Response

Error Response

Delete A Rule

Request Details

Success Response