What is the Replace Response Handler?

The Replace Response Handler allows you to modify the content of responses by replacing specific text patterns with alternative content. This powerful handler enables you to make changes to HTML, JSON, CSS, JavaScript, or text responses before they are delivered to the browser, all without modifying your upstream server's code.

How Replace Response Handler Works

When a rule with a Replace Response Handler matches an incoming request, the request is first forwarded to your upstream server. Once the response is received, the handler scans the response body for the specified search patterns and replaces them with your defined replacements. This happens transparently to both your upstream server and the end user.

The handler performs a simple text-based search and replace operation, making it work for any text-based response format including HTML, JSON, XML, CSS, JavaScript, or plain text.

Configuration Options

The Replace Response Handler requires a list of search and replace pairs:

Option	Type	Required	Description
`replacements`	`array`	Yes	An array of search and replace pairs to apply to the response body

Each replacement object within the array has these properties:

Property	Type	Required	Description
`search`	`string`	Yes	The text pattern to search for in the response body
`replace`	`string`	Yes	The text to replace matches with

API Reference

When working with Rules through the API, Replace Response handlers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.

{
  "type": "replace_response",
  "replacements": [
    {
      "search": "example.com",
      "replace": "customdomain.com"
    },
    {
      "search": "Original Content",
      "replace": "Modified Content"
    }
  ]
}

In API requests, this handler would be included in the handlers array of a rule object:

{
  "name": "Domain Name Replacement Rule",
  "active": true,
  "matchers": [],
  "handlers": [
    {
      "type": "replace_response",
      "replacements": [
        {
          "search": "example.com",
          "replace": "customdomain.com"
        },
        {
          "search": "Original Content",
          "replace": "Modified Content"
        }
      ]
    }
  ]
}

Configuration Examples

Example 1: Domain Name Replacement

This handler will replace all instances of one domain with another:

In the UI:

In the API:

{
  "type": "replace_response",
  "replacements": [
    {
      "search": "mydomain.example.com",
      "replace": "custom-brand.com"
    }
  ]
}

Example 2: Modifying HTML Content

This handler will update display text throughout your site:

In the UI:

In the API:

{
  "type": "replace_response",
  "replacements": [
    {
      "search": "<h1>Welcome to Our Platform</h1>",
      "replace": "<h1>Welcome to BrandName Solutions</h1>"
    },
    {
      "search": "<footer>© 2023 Generic Company</footer>",
      "replace": "<footer>© 2023 BrandName Solutions</footer>"
    }
  ]
}

Example 3: Fixing Links and Resources

This handler will update resource paths for a subdirectory deployment:

In the UI:

In the API:

{
  "type": "replace_response",
  "replacements": [
    {
      "search": "src=\"/assets/",
      "replace": "src=\"/subdirectory/assets/"
    },
    {
      "search": "href=\"/css/",
      "replace": "href=\"/subdirectory/css/"
    }
  ]
}

Example 4: Updating API Responses

This handler will modify JSON responses from an API:

In the UI:

In the API:

{
  "type": "replace_response",
  "replacements": [
    {
      "search": "\"apiVersion\": \"1.0\"",
      "replace": "\"apiVersion\": \"2.0\", \"customField\": \"customValue\""
    }
  ]
}

This can be used to add or modify fields in JSON responses without changing the API code.

Common Use Cases

Here are some popular ways to use the Replace Response Handler:

White-Labeling Services

Customize third-party services to match your branding:

Create rules targeting all pages or specific pages
Replace the service provider's branding with your own
Update references to the original domain with your custom domain
Modify color schemes or styling through CSS replacements

Fixing Legacy Content

Update content from older systems without modifying the source:

Replace outdated information or references
Fix broken links by updating URL patterns
Update copyright notices or outdated company information
Modernize HTML without changing backend systems

Path Correction

Fix resource paths when hosting applications in unexpected configurations:

Correct absolute paths when hosting in subdirectories
Update CDN references to use your custom domain
Fix protocol-relative URLs (//example.com/) to use HTTPS

Content Injection

Add content to pages without modifying application code:

Add analytics scripts to all pages
Insert custom headers, footers, or sidebars
Add notification banners or announcements
Insert privacy notices or cookie consent mechanisms

Content Redaction

Remove sensitive information from responses:

Replace internal IPs or server information with generic values
Remove development comments or debug information
Redact specific error messages that might reveal system details
Replace user identifiers with anonymized values

Temporary Fixes

Implement quick solutions while waiting for upstream changes:

Replace incorrect information until source can be updated
Fix spelling or grammar errors across the site
Update pricing or feature information temporarily
Correct mistakes in API responses

Combining with Other Handlers

The Replace Response handler works well when combined with:

Rewrite Handler: Change the URL structure before fetching content
Set Response Header: Add or modify headers along with content changes
Static Response: In some cases, a complete replacement might be simpler than multiple text replacements

Since Replace Response modifies the content after it's retrieved from the upstream server, it should typically be placed after handlers that modify the request (like Rewrite) but before handlers that need to work with the modified content.

Best Practices

Be as specific as possible with search patterns to avoid unintended replacements
Test replacements thoroughly, especially when working with HTML or JavaScript
Consider the impact on page rendering performance for large or numerous replacements
Be cautious with replacements in JavaScript or JSON as syntax errors can break functionality
Use this handler for targeted changes rather than complete page rewrites
Document your replacements for easier maintenance
Consider caching implications if your replacements change frequently

Troubleshooting

If your Replace Response handler isn't working as expected:

Verify that your matchers are correctly identifying the requests
Check that your search text matches exactly what's in the response (including whitespace and casing)
Inspect the original response to confirm what you're trying to replace exists
Start with simpler, more specific replacements before attempting complex patterns
Remember that replace operations happen sequentially in the order listed
Consider content encoding (ensure the response isn't compressed/binary)
Check for dynamic content that might vary between requests

Limitations

Replacements are simple text substitutions, not regular expressions
Large numbers of replacements may impact performance
Works only with text-based responses, not binary content
Cannot make decisions based on document structure or context
Replacements occur in the order specified, which may affect results if patterns overlap
Maximum response size for replacement operations is limited (consult your plan details)

The Replace Response handler provides a powerful way to modify content on-the-fly without requiring changes to your upstream applications. By strategically using text replacements, you can customize appearances, fix issues, and adapt content to your specific needs.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!