Skip to main content
Version: Next

Filter Processor

Overview​

The Filter processor allows filtering of API requests and responses based on various criteria such as URL, HTTP method, headers, and status codes. This enables precise control over traffic by allowing or blocking specific requests according to defined rules.

Filter

Input and Output​

This processor typically operates on the request stream:

  • Input Stream: Request/Response – When a request enters the flow, the processor checks if it meets the filter criteria.

  • Output Stream: Request/Response -

    • If the Request matches the criteria, it continues through the request stream as usual.

    • If the Request does not match, the request is sent to the GenerateResponse Processor.

    • If the Response matches the retry criteria (e.g., a specific status code), it continues through the response stream to the client.

By controlling request and response flow, the Filter processor helps enforce business logic, optimize API traffic, and manage retries efficiently.

Parameters​

Each parameter is defined as a key-value pair inside the parameters section.

url​

Type: string
Required: False
Filters requests based on the full URL.

Example:

- key: url
  value: "https://api.example.com"

endpoint​

Type: string
Required: False
Filters requests based on an endpoint path. Wildcards such as * are supported.

Example:

- key: endpoint
  value: "/users/*"
note

In order to properly filter based on a specific endpoint, make sure to specificy the API Provider as well.

method​

Type: string
Required: False
Filters requests based on the HTTP method (GET, POST, etc.).

Example:

- key: method
  value: GET

Type: string
Required: False
Filters requests based on a specific HTTP header.

Example:

- key: header
  value: x-lunar-consumer-tag=dev

expressions​

Type: string
Required: False
Filters request or response based on specific JSONPath expressions.

Example:

  - key: expressions
    value:
      - $.request[?(@.method == 'POST' || @.method == 'GET')]
      - $.response[?(@.status >= 200 && @.status <= 300)]

status_code_range​

Type: string
Required: False
Use in conjunction with the Retry Flow, this filters responses based on a range of HTTP status codes (e.g., 100-599) to determine if the request should be re-sent to the provider.

Example:

- key: status_code_range
  value: "400-499"
note

The status codes must be a range. If you wish to filter on a single code define it as the whole range, e.g. 403-403.

Best Practices​

  • Use url for exact URL filtering and endpoint for broader path-based filtering.
  • Set method to filter specific HTTP methods and control request behavior.
  • Use header filtering to identify specific request sources.
  • Specify a status_code_range to monitor success, client errors, or server errors.

For more details on configuring flows, visit the Lunar.dev Flows Documentation.

Filter Processor Template​

Filter:
  processor: Filter
  parameters:
    - key: url
      value: "https://api.example.com/resource/users/*"
    - key: method
      value: POST
    - key: status_code_range
      value: "200-299"
    - key: header
      value: "X-Auth-Token"={auth_token}
    - key: expressions
      value:
        - $.request[?(@.method == 'POST' || @.method == 'GET')]
        - $.response[?(@.status >= 200 && @.status <= 300)]

Use Case​

In the following usecase you will allow any requests to httpbin as long as the request doens't have the header x-lunar-consumer-tag = dev

Filter Processors Example
AllowFilter:
 processor: Filter # Processor for allowing requests to specific URLs
 parameters:
   - key: url
     value: httpbin.com/* # Allow only requests to httpbin.com

BlockFilter:
 processor: Filter # Processor for blocking requests based on a header
 parameters:
   - key: header
     value: x-lunar-consumer-tag=dev # Header used for blocking access