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
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 matchesREGEX - request path/URL matches a regular expressionB_CO - request body containsB_REGEX - request body matches a regular expressionH_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) |
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 |
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
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 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. Whenrule-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
}
}