Skip to main content

Path Matcher

The Path matcher lets you create rules based on the URL path component. Learn how to match requests using exact paths, prefixes, suffixes, and other powerful path-matching patterns.

Drago Crnjac avatar
Written by Drago Crnjac
Updated over a month ago

What is the Path Matcher?

The Path matcher allows you to create rules that match requests based on the URL path component. This is one of the most commonly used matchers as it lets you control how different sections of your website or application are handled.

How Path Matcher Works

The Path matcher evaluates the path portion of the URL (everything after the domain name and before any query parameters). For example, in the URL https://example.com/blog/articles?id=123, the path is /blog/articles.

Available Operators

The Path matcher supports these comparison operators:

Operator

Description

Example

is

Exact path match

/contact matches only /contact

is_not

Path does not match exactly

/contact matches anything except /contact

starts_with

Path begins with the value

/blog matches /blog, /blog/articles, /blog-posts, etc.

ends_with

Path ends with the value

.pdf matches /documents/report.pdf, /invoice.pdf, etc.

contains

Path contains the specified value

product matches /products, /category/product-list, etc.

does_not_contain

Path does not contain the value

admin matches any path that doesn't include "admin"

has_any_value

Path exists (any non-empty value)

Matches any request with a path

is_unknown

Path does not exist

Matches requests to the root path /

API Reference

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

Configuration Examples

Example 1: Basic Blog Redirect

This matcher will match any path that starts with /blog/:


​In the UI:

In the API:

{
  "type": "path",
  "value": "/blog/",
  "operator": "starts_with"
}

Example 2: Excluding Admin Section

This matcher will match paths that do not contain "admin":

In the UI:

In the API:

{
  "type": "path",
  "value": "admin",
  "operator": "does_not_contain"
}

Example 3: PDF File Handling

This matcher will match any path that ends with ".pdf":

In the UI:

In the API:

{
  "type": "path",
  "value": ".pdf",
  "operator": "ends_with"
}

Example 4: Specific Page Match

This matcher will match exactly the "/contact" page:

In the UI:

In the API:

{
  "type": "path",
  "value": "/contact",
  "operator": "is"
}

Example 5: Homepage Only

This matcher will match only the root path:

In the UI:

In the API:

{
  "type": "path",
  "value": "/",
  "operator": "is"
}

Common Use Cases

Here are some popular ways to use the Path matcher:

Redirecting Legacy URLs

If you've restructured your website, you can redirect old URLs to new ones:

  1. Create a rule with a Path matcher using is operator for the old path

  2. Add a Set Response Header handler and set the Location header to the new URL

  3. Add a Static Response handler with a 301 status code

Section-Specific Headers

Add special headers to specific sections of your site:

  1. Create a rule with a Path matcher using starts_with for your section (e.g., /docs/)

  2. Add a Set Response Header handler to add custom caching or security headers

Serving Static Content

Create a rule to serve static content for specific paths:

  1. Create a rule with a Path matcher using starts_with for static content paths (e.g., /static/)

  2. Add a Static Response handler to serve the content directly

Protecting Admin Areas

Add authentication requirements to admin sections:

  1. Create a rule with a Path matcher using starts_with for admin paths (e.g., /admin/)

  2. Add handlers to verify authentication headers or redirect to a login page

Combining with Other Matchers

The Path matcher becomes even more powerful when combined with other matchers. For example:

  • Path + Method: Match only GET requests to specific paths

  • Path + Header: Match requests to specific paths that include certain headers

  • Path + Query: Match paths that also include specific query parameters

Remember that when multiple matchers are used in a rule, ALL must match to apply the rule (AND logic).

Best Practices

  • Be precise with your path patterns to avoid unintended matches

  • For root domain matching, use is with value /

  • Use starts_with for section-based rules (like /blog/, /api/, etc.)

  • Consider case sensitivity - paths are matched exactly as specified

  • Test your path matchers thoroughly with different URL variations

  • Order your rules carefully since multiple matching rules will execute in order

Wildcards and Path Matching

While not using regex directly, the Path matcher provides wildcard-like functionality through its operators:

  • starts_with acts like a trailing wildcard (/blog/*)

  • ends_with acts like a leading wildcard (*.pdf)

  • contains acts like wildcards on both sides (*/blog/*)

Troubleshooting

If your Path matcher isn't working as expected:

  1. Check for exact spelling and case matching

  2. Verify that you've chosen the correct operator

  3. Ensure your path starts with a forward slash / when appropriate

  4. Test with and without trailing slashes as they are considered different paths

With the Path matcher, you can create sophisticated routing rules based on URL paths. As you become more familiar with it, you'll discover many ways to enhance your domain's behavior without modifying your application code.

Until next time, keep building!

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

Did this answer your question?