Understanding Regex in Kong Gateway: Then vs Now

Whether you're building scalable APIs or managing complex traffic flows, Kong Gateway offers powerful routing capabilities — and at the heart of that power lies one timeless tool: regular expressions (regex).

Regex gives you fine-grained control over how requests are matched, routed, or filtered. But like everything else, Kong's support for regex has evolved significantly — especially with the introduction of expressions in newer versions.

In this post, let’s dive deep into:

• How regex worked in earlier versions of Kong
• What’s changed in Kong 3.x and beyond
• Practical use cases and syntax examples
• When to use plain regex and when to switch to expressions

🔍 What is Regex in Kong?

Regular expressions are string patterns that allow matching flexible and complex inputs — such as paths, headers, hostnames, and even query parameters.

In Kong, regex is typically used to:

• Match incoming request paths (e.g., /users/123)
• Match hostnames (e.g., *.example.com)
• Filter headers like X-User-Type: admin

You can write regex patterns in route fields such as paths, hosts, or headers, and Kong will evaluate them to decide whether a request should be routed.

📜 Regex in Older Kong Versions (Pre-3.x)

In earlier Kong versions, regex was supported — but only within a few specific fields:

• Use regex in paths, like /api/v1/users/\d+
• Use regex in headers, with special syntax like ~ for case-sensitive, and ~* for case-insensitive matching
• Combine multiple route conditions — but they were evaluated separately and limited in complexity

🧪 Example 1: Regex in Path

"paths": ["/users/\d+"]

🧪 Example 2: Regex in Header

"headers": {
"x-role": ["~^admin$"]
}

⚠️ Limitations in the Past

While powerful, this older approach came with limitations:

• ❌ No way to write complex combined conditions (e.g., header + path regex)
• ❌ Couldn’t easily use request method (GET, POST) in regex logic
• ❌ Static matching — no dynamic plugin control or conditional logic
• ❌ Managing multiple routes with slightly different patterns became messy

⚡ Regex in Modern Kong (v3.0 – v3.7+)

With the evolution of Kong Gateway (starting around v3.0), expressions were introduced — bringing more power, flexibility, and logical operations to routing and plugin control.

✅ Good News: Regex still works!

Regex is still fully supported in:

• paths
• hosts
• headers

But now, you also get regex support inside expressions, unlocking much more power.

🧠 What Are Expressions?

Expressions in Kong are Lua-style conditions that can evaluate fields like:

• request.path
• request.headers
• request.method
• request.query
• request.jwt.claims

And yes — you can use regex functions like string.match() and ngx.re.match() inside them.

🔁 Regex vs Expressions in Kong (Tabular View)

Here’s how the two approaches compare:

💡 Real-World Use Cases

1. Path Matching with Regex

"paths": ["/orders/\d{4,6}"]
Matches /orders/1234 or /orders/654321.

1. Header Matching with Regex

"headers": {
"x-region": ["~^apac-.*$"]
}
Matches x-region: apac-east or apac-west.

1. Expression with Regex (New Style)

expression = "ngx.re.match(request.path, '^/reports/[0-9]{4}/[a-z]+$')"

1. Case-Insensitive Header Match using Expressions

expression = "string.lower(request.headers['x-department']) == 'finance'"

✅ Tips for Writing Safe Regex in Kong

• Escape special characters properly in JSON/YAML (use \)
• Use ~* for case-insensitive matches
• Test with https://regex101.com/ before deploying
• Prefer expressions for combined, readable logic
• Be cautious — overly complex regex can slow down high-throughput routes

📦 Summary

Regex is still a cornerstone of Kong Gateway’s routing power — but the introduction of expressions has taken it to the next level.

• 🏷️ Older versions = regex only in a few places, limited flexibility
• 🧠 Newer versions (3.0+) = regex plus full-blown logic with expressions
• 🔄 Use regex where it makes sense (simple patterns)
• ⚙️ Use expressions for more advanced routing or plugin logic

🧩 Final Thoughts

Regex hasn’t gone anywhere — but it now has a smarter companion in Kong expressions.

By combining the two, you can create more dynamic, maintainable, and secure Kong configurations.

So… are you still using regex the old way?

Try expressions with regex today — and level up your API Gateway game! 💥