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 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)
`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. 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​

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

Success Response​

Error Response​

Request Example - Create a rule to match HTTP header​

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

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

Success Response

Error Response

Request Example - Create a rule to match HTTP header

Update A Rule

Endpoint

Request

Success Response

Error Response

Delete A Rule

Request Details

Success Response