HTTP Proxy Rule (Callout)

The Proxy or Callout Rule feature in Beeceptor enables you to accept incoming HTTP requests and trigger an HTTP callout. This powerful feature allows you to forward the original request as-is or transform the URL and request payload to meet your integration needs. It's particularly useful for simulating asynchronous APIs during development and testing, providing a flexible tool for advanced mock server configurations.

Proxy Rule Execution

Behavior Selection

When configuring a Proxy or Callout Rule, you need to select the desired behavior for handling requests. There are two types of behavior to choose from:

• Synchronous Behavior: If you select the synchronous behavior option, the original request will wait for the callout's response. The entire response, including headers, status code, and payload, received from the callout will be routed back to the original caller. This ensures that the response from the callout is seamlessly integrated into the original request's flow.
• Asynchronous Behavior: If you select the asynchronous behavior option, the original request will not wait for the callout to complete. Instead, you can define the response headers, status code, and payload, which will be returned instantly. After sending the instant response, an HTTP callout will be triggered. This is a non-blocking operations where the original request does not depend on the callout's completion.

Execution Flow

A Proxy or Callout Rule involves two main HTTP requests:

1. An Original Request: This request originates from the client. The response to this can be synchronous (waiting for the callout response) or asynchronous (immediate mock response) as described in the next section.
2. A New HTTP Callout: This request is triggered by Beeceptor, and sent to a specified webhook or HTTP endpoint.

Refer to the below sequence diagrams to understand the execution flow when a proxy rule is activated. The diagrams illustrate both the requests and execution flow.

Synchronous Behavior	Asynchronous Behavior
The original request waits for the callout's response.	The original request does not wait for the callout to complete.
The entire response received from the callout is routed back to the original caller.	An instant mock response is sent. This can be customized.
Example: Integration of two services where the request payload needs to be transformed before hitting the next API.	Example: Simulating asynchronous API behavior where the original request initiates a background process.

How To Configure A Proxy Rule

Configure Proxy Rule

Follow these steps to configure a proxy rule in Beeceptor:

1. Navigate to your endpoint's dashboard and click on 'Mock rules' to open the list of rules.

2. Select 'Additional Rule Types' and click on 'Create Proxy or Callout'.

3. In the 'Create Rule' screen, define the request matching criteria just like in standard rules. Specify parameters such as HTTP method, URL path, headers, and query parameters to match.

4. In the 'Synchronous Response Configuration' section, select the response behavior. Choose whether the original request should wait for the callout's response or if an instant mock response should be sent.

   • Wait for Callout Response: The original request waits for the callout's response. The response (headers, status code, payload) received from the callout is routed back to the original caller.
   • Instant Mock Response: Send an immediate mock response without waiting for the callout's response.

5. In the 'Asynchronous Request Configuration (HTTP Callout)' section, define the callout parameters. Specify the HTTP method and request path where the request should be triggered. You can choose to create a new request payload or forward the original request as-is. You can enable the template engine to include parameters from the original request payload, query parameters, or mocked response payload.

Build Dynamic Callout Payload

When setting up a custom payload for the HTTP callout, you can dynamically reuse data from the incoming request to build the payload for the outgoing call. Below are the avaiable helpers you can use in your templates.

Request Payload

The oReqBody helper is used to reference a specific field from the payload of the original request that Beeceptor received. It allows you to dynamically include data from the original request in the callout's request payload.

Syntax:

{
   "key": "{{oReqBody 'fieldName'}}"
}

Mocked Response Payload

The oResBody helper refers to the body of the mocked response generated for the original request. It’s especially useful in asynchronous workflows where the HTTP callout occurs after the original request has been responded with mock payload.

Syntax:

{
   "mockResponseData": "{{oResBody 'responseField'}}"
}

Here, replace responseField with the appropriate field from the mocked response body.

Request's Query Parameter

Use oReqQueryParam helper to access query parameters from the original request.

{
   "queryParam": "{{oReqQueryParam 'paramName'}}"
}

Use Cases

The Proxy Rule or HTTP Callout feature in Beeceptor powers a variety of use-cases.

• Simulation of Asynchronous APIs: Enables developers to simulate real-world API interactions and ensure the application handles asynchronous responses correctly.
• Service Integration and Payload Transformation: Integrate two services by transforming the payload between them. For example, you can transform an incoming request payload and forward it to another service with a modified structure.
• Conditional Routing Based on Request Parameters: You can route requests to different endpoints based on specific request parameters. Example: When the HTTP header
  • has Authorization: API-key-A in, forward the request to microservice A, or
  • when the Authorization: API-key-B, forward to microservice A.
• Webhook Storage and Routing Store, Log and monitor all incoming requests and their respective callouts. Record each request and callout in Beeceptor's request history for auditing purposes. Benefit: Improves traceability and debugging capabilities, ensuring all interactions are logged and can be reviewed.
• Custom Workflows and Automation: You can implement custom workflows by triggering HTTP callouts based on specific request criteria. For example, you can automate downstream processes by forwarding requests to automated systems or services.

How It Differs From Proxy Setup

The Proxy Rule feature differs from the Proxy Setup feature in a few key ways:

	Proxy Setup	Proxy Rule
Scope	Proxy Setup operates at the entire mock server level (domain).	Proxy Rule feature works for selective requests.
Activation	Any request that does not match the list of mock rules activates (domain) proxy setup.	You can selectively activate the proxy rule based on request parameters.
Modification	No modification is allowed for the request path or payload.	Allows modification of the callout request's path and payload.
Configuration	You only specify the base domain during configuration; the request path is copied as is.	You need to specify response behavior, absolute HTTP endpoint, build callout request payload, etc., having full control.

Both features offer different levels of control over the behavior of the mock server (a Beeceptor endpoint). Pick the one that suits your use case best.