Skip to content
Kong Logo | Kong Docs Logo
search
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.5.x (latest)
  • Home icon
  • Kong Gateway
  • Key Concepts
  • Routes
  • How to Configure Routes using Expressions
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.5.x (latest)
  • 3.4.x
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Prerequisites
  • Create routes with expressions
    • Create complex routes with expressions
  • Matching fields
  • More information

How to Configure Routes using Expressions

Configuring routes using expressions allows for more flexibility and better performance when dealing with complex or large configurations. This how-to guide explains how to switch to the expressions router and how to configure routes with the new expressive domain specific language. Familiar yourself with the Expressions Language Reference before proceeding through the rest of this guide.

Prerequisites

Edit the kong.conf to contain the line router_flavor = expressions and restart Kong Gateway.

Note: Once you enable expressions, the match fields that traditionally exist on the route object (such as paths and methods) will no longer be configurable and you must specify Expressions in the expression field. A new field priority will be made available that allows specifying the order of evaluation of configured Expression routes.

Create routes with expressions

To create a new route object using expressions, send a POST request to the services endpoint:

curl --request POST \
  --url http://localhost:8001/services/example-service/routes \
  --form-string expression='http.path == "/mock"'

In this example, you associated a new route object with the path /mock to the existing service example-service. The Expressions DSL also allows you to create complex router match conditions:

curl --request POST \
  --url http://localhost:8001/services/example-service/routes \
  --header 'Content-Type: multipart/form-data' \
  --form-string 'expression=(http.path == "/mock" || net.protocol == "https")'

Create complex routes with expressions

You can describe complex route objects using operators within a POST request:


curl --request POST \
  --url http://localhost:8001/services/example-service/routes \
  --header 'Content-Type: multipart/form-data' \
  --form-string name=complex_object \
  --form-string 'expression=(net.protocol == "http" || net.protocol == "https") &&
                (http.method == "GET" || http.method == "POST") &&
                (http.host == "example.com" || http.host == "example.test") &&
                (http.path ^= "/mock" || http.path ^= "/mocking") &&
                http.headers.x_another_header == "example_header" && (http.headers.x_my_header == "example" || http.headers.x_my_header == "example2")'

See the expressions language overview page for common use cases and how to write expressions routes for them.

For a list of all available language features, see the expressions language reference.

Matching fields

The following table describes the available matching fields, as well as their associated type when using an expressions based router.

Field Type Available in HTTP Subsystem Available in Stream Subsystem Description
net.protocol String ✅ ✅ Protocol of the route. Roughly equivalent to the protocols field on the Route entity. Note: Configured protocols on the Route entity are always added to the top level of the generated route but additional constraints can be provided by using the net.prococol field directly inside the expression.
tls.sni String ✅ ✅ If the connection is over TLS, the server_name extention from the ClientHello packet.
http.method String ✅ ❌ The method of the incoming HTTP request. (for example, "GET" or "POST")
http.host String ✅ ❌ The Host header of the incoming HTTP request.
http.path String ✅ ❌ The normalized request path. This field value does not contain any query parameters that might exist.
http.headers.<header_name> String[] ✅ ❌ The value(s) of request header <header_name>. Note: The header name is always normalized to the underscore and lowercase form, so Foo-Bar, Foo_Bar, and fOo-BAr all become values of the http.headers.foo_bar field.
http.queries.<query_parameter_name> String[] ✅ ❌ The value(s) of query parameter <query_parameter_name>.
net.src.ip IpAddr ❌ ✅ IP address of the client.
net.src.port Int ❌ ✅ The port number used by the client to connect.
net.dst.ip IpAddr ❌ ✅ Listening IP address where Kong Gateway accepted the incoming connection.
net.dst.port Int ❌ ✅ Listening port number where Kong Gateway accepted the incoming connection.

More information

  • Expressions Language Reference
  • Repository for the Expressions router engine
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Gateway Enterprise Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2023