Skip to content

HTTP Filter Trigger

The HTTP filter trigger in Martini allows developers to conditionally invoke services and workflows based on the characteristics of incoming HTTP requests. This functionality enables the execution of specific services and workflows only when the incoming request satisfies predefined conditions set in the HTTP filter trigger's configuration. Requests that do not meet these conditions are ignored, and the associated service or workflow is not activated.

Martini integrates this feature by registering a filter for each HTTP filter trigger, utilizing Java's standard mechanisms for filtering requests and responses.

Usage in Workflows

To learn how to setup and use the HTTP Filter trigger in workflows, see Martini Workflows Trigger Nodes

Usage in Services

To learn how to setup and use the HTTP Filter trigger in services, see Invoking Services via a Trigger

Properties

The configuration of an HTTP filter trigger includes both general properties applicable to all triggers and specific settings unique to the HTTP filter trigger.

HTTP Filter-Specific Configuration

Below are the properties specific to HTTP filter triggers:

Property Default Description
Priority 2147483647 Determines the execution order among HTTP filter triggers with the same filter order. A lower number indicates a higher priority.
Filter order (required) Specifies the phase during which Martini should authenticate the request relative to the filter's execution.
Path pattern type (required) Defines the type of path patterns (glob pattern or regular expression pattern) to match against incoming requests.
Path patterns (required) A set of request path patterns that incoming requests must match to trigger the configured service or workflow.
Case sensitive true Indicates if path pattern matching should consider case sensitivity.
Request methods (required) Lists the HTTP methods an incoming request must use to qualify for triggering the configured service or workflow.

Parameters

HTTP filter triggers support specific parameters that provide detailed context about the matching request and allow for comprehensive control over the request-response process.

HTTP Filter-Specific Parameters

Name Type Description
$__request javax.servlet.http.HttpServletRequest The HttpServletRequest object for the incoming request.
$__response javax.servlet.http.HttpServletResponse The HttpServletResponse object paired with the request.
$__chain javax.servlet.FilterChain Controls the continuation or termination of the filter chain.
uri java.lang.String The URI of the incoming request.
url java.lang.String The full URL of the request.
method java.lang.String The HTTP method used by the request.
user java.security.Principal The authenticated user for the request, applicable only in certain contexts.

Return Values

Services or workflows linked with HTTP filter triggers can specify return values to alter the behavior of the filter chain.

Name Type Description
$__newRequest javax.servlet.http.HttpServletRequest Substitutes the original request with a new one for subsequent filters.
$__newResponse javax.servlet.http.HttpServletResponse Substitutes the original response with a new one for subsequent filters.
$__discontinueChain boolean Determines whether to halt the filter chain. A value of true signifies that Martini assumes the service or workflow will handle the invocation of subsequent filters manually.

Notes and Tips

  • The registration of the filter corresponding to a trigger is managed by Martini and occurs upon the trigger's activation, with deregistration upon deactivation.

Example: Groovy Method

This Groovy example demonstrates how to manipulate HTTP response headers by injecting 'X'-prefixed request headers into the response, converting their values to uppercase:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import javax.servlet.http.HttpServletRequest
import javax.servlet.http.HttpServletResponse
import javax.servlet.http.HttpServletResponseWrapper

class HttpFilterExamples {

    /**
     * Alters the response to include 'X'-prefixed request headers as response headers,
     * transforming their values to uppercase.
     *
     * @param $__request the matched request
     * @param $__response the response for the matched request
     * @return an altered response object
     */
    static HttpServletResponse toUppercaseXPrefixedHeaders(
        HttpServletRequest $__request, HttpServletResponse $__response ) {

        HttpServletResponseWrapper responseWrapper = new HttpServletResponseWrapper($__response);
        Enumeration<String> headers = $__request.getHeaderNames();
        while (headers.hasMoreElements()) {
            String header = headers.nextElement();
            if (header.toUpperCase().startsWith("X-")) {
                Enumeration<String> values = $__request.getHeaders(header);
                while (values.hasMoreElements()) {
                    String value = values.nextElement();
                    responseWrapper.addHeader(header, value.toUpperCase());
                }
            }
        }

        return responseWrapper;
    }
}

This method intercepts the incoming HTTP request, checks for headers that start with 'X-', and re-injects them into the response with their values converted to uppercase. This example illustrates how HTTP filter triggers can be leveraged for dynamic request/response manipulation in Martini, showcasing the platform's flexibility in integrating custom logic within HTTP workflows.

Custom Authentication Using HTTP Filter Triggers

HTTP filter triggers let you implement custom authentication logic by intercepting and processing HTTP requests before they reach your API endpoints. This is useful when the standard authentication mechanisms (OAuth 2.0, Basic Authentication) do not meet your requirements.

See the section below for a step-by-step guide on how to set up custom authentication using HTTP filter triggers, including configuration, usage, and troubleshooting tips.

How to Set Up Custom Authentication with HTTP Filter Triggers

Create a custom authentication filter for your REST API:

  1. Create a Martini Package
  2. Create a new workflow in your Martini package (see Creating Workflows)
  3. Implement your authentication logic in the workflow
  4. Add the HTTP Filter Trigger Trigger Node to your package:
  5. Click the + sign in the Workflow Designer
  6. Choose HTTP Filter Trigger
  7. Configure the trigger properties as described in HTTP Filter Trigger Properties

✅ Expected result: Incoming requests are intercepted and authenticated using your custom logic before reaching your API endpoints.

How It Works

📺 Video Tutorial: For a visual walkthrough of how to work with the HTTP filter trigger, see Invoking Services via HTTP Filter Trigger

Why It Matters

Custom authentication filters give you complete control over your security logic without being limited to standard authentication types. This approach is perfect for integrating with proprietary authentication systems, implementing complex authorization rules, or adding custom security headers to responses.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Filter not triggering Authentication logic never executes Path patterns don't match requests Update path patterns to match your API endpoints All versions
Filter order conflicts Authentication runs at wrong time Incorrect filter order setting Ensure the right timing is indicated in Filter Order, whether it "Pre Authentication (Before Auth)" or "Post Authentication (After Auth) All versions

Inspecting Request Headers

Request header inspection allows you to examine and validate specific headers for authentication and authorization purposes.

Getting Started

Extract and validate request headers in your authentication service:

  1. Add a Map Node in your HTTP filter service
  2. Declare a variable for the header value you want to extract (e.g., token)

  3. Add a set expression to map the header value:

    • Right-click on your variable and select Set Expression
    • Ensure that the selected Language is Groovy

      You can find the Language dropdown at the bottom of the Edit Set Expression window

    • Enter $__request.getHeader("HeaderName") replacing "HeaderName" with the actual header you want to extract

    Examples:

    • $__request.getHeader("Authorization") to extract the Authorization header
    • $__request.getHeader("X-API-Key") to extract custom API key headers

  4. Implement validation logic using the extracted header values in subsequent service steps

For more details on declaring variables and using set expressions in a Workflow, see Workflow Designer.

✅ Expected result: Your workflow can access request headers and implement custom validation logic based on header values.

How It Works

Header inspection operates within your HTTP filter service:

  1. Request arrives with various HTTP headers
  2. Service accesses headers using $__request.getHeader() or $__request.getHeaders()
  3. Validation logic runs against header values
  4. Decision made to allow, reject, or modify the request
  5. Response sent with appropriate status codes and messages

Common header inspection pattern examples:

  • API Key validation - Check X-API-Key or Authorization headers
  • Version checking - Validate X-Client-Version or User-Agent
  • Rate limiting - Inspect X-Forwarded-For for IP-based limits
  • Custom authentication - Process proprietary authentication headers

Why It Matters

Header inspection enables sophisticated authentication schemes that go beyond simple token validation. You can implement multi-factor authentication, API versioning enforcement, client validation, and custom security policies based on request metadata.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Headers not found getHeader() returns null Header name case mismatch Use exact header name case or iterate through all headers All versions
Multiple header values Only first value retrieved Using getHeader() instead of getHeaders() Use getHeaders() to get all values for multi-value headers All versions
Empty header values Header exists but value is empty Client sending empty header Check for null/empty values before processing All versions