Skip to main content

Manage Mocking Rules

You can manage an endpoint's mocking rules via API. These will help you build use-cases to create or update mocking rules programmatically and later send the request. Any update to mocking rules is reflected in real-time.

Rule Selection

An endpoint can have multiple mocking rules. These rules can match requests based on request's path or contents in the request's body. When a request is sent to a Beeceptor endpoint, mocking rules are evaluated in displayed order. The first rule qualifying the criteria is selected to serve the response.

Get All Rules

List all rules configured for an endpoint.

Request Details

MethodRequest Path
GEThttps://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 parametersDetails
ididentifier to uniquely identifies this rule.
enabledDefault - true. Helps you turn on/off a rule to skip evaluation.
mockDefault - 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.
descriptionOptional. Description of the rule
delayIndicates if this rule should respond after these milliseconds
match.methodDuring rule evaluation, filter request with this method (GET, POST, PUT, etc). This will be applied as AND logic with operator parameter.
match.operatorOperator 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.valueDuring rule evaluation, match the request path with this value. (operator is used to match against this value)
send.statusWhen the rule is matched, response HTTP status code to send.
send.bodyWhen the rule is matched, response body to send.
send.headersWhen the rule is matched, response headers to send.
send.templatedOptional. Enable HandlesBar templates in the mocked response. Defaults to false. Read more 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

MethodRequest Path
GEThttps://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 MethodRequest Path
POSThttps://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules/
  • <my-endpoint> - name of the Beeceptor endpoint

Request Example - Create a rule to match request path starting with

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" : false,
"mock" : false,
"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": false,
"mock": false,
"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": "jwmk5way3r"
}
}

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

Request Example - Create a rule to match 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,
"mock": true,
"send": {
"status": 299,
"body": "{ \"status\": \"SOME_VALUE_IN_HEADER - Awesome!\"}",
"headers": {
"Content-Type": "application/json"
},
"templated": false
},
"enabled": true
}

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 MethodRequest Path
PUThttps://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

MethodRequest Path
DELETEhttps://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/rules
DELETEhttps://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
}
}