Request matching is the first stage in Tyk Gateway’s routing pipeline. Before any other processing occurs, it must determine which API definition and which endpoint owns the incoming request. Only when a match is found does further processing take place.
Matching happens at two levels:
- API-level: Tyk Gateway compares the request URL against the listen paths of all registered APIs to identify which API definition to use.
- Endpoint-level: Within the matched API, Tyk Gateway compares the remainder of the request path against the endpoint patterns defined in the API definition to identify which endpoint configuration applies.
The Request URL
When a client sends a request to an API hosted on Tyk Gateway, the URL follows this structure:
<protocol>://<domain>/<listenPath>/<endpointPath>
protocol is the scheme, domain is the authority, and listenPath/endpointPath together form the path.
- The listen path is defined in the API definition. Tyk Gateway compares the incoming URL (after stripping the domain) against all registered listen paths to identify the correct API definition.
- The endpoint path is the remainder of the URL after the listen path (and any version identifier). This is compared against the endpoint patterns in the matched API definition.
If no API listen path matches the request, Tyk Gateway returns HTTP 404 Not Found.
Tyk Gateway acts as a reverse proxy. When forwarding a request upstream, it replaces its own hostname with the upstream target URL configured in the API definition. The strip listen path option removes the listen path from the upstream request, allowing a cleaner public API facade over a legacy upstream service. API-Level Matching: The Listen Path
Tyk Gateway treats the listen path configured in an API definition as a regular expression, enabling advanced users to perform complex listen path matching.
Path Ordering
Before attempting to match an incoming request against registered listen paths, all loaded API definitions are sorted into a priority order. The Gateway tests each listen path in turn and uses the first match it finds. Understanding this ordering is important when multiple APIs have similar or overlapping listen paths.
The ordering rules are:
- APIs are divided into two groups: those with a custom domain configured, and those without. APIs with a custom domain take priority.
- Within each group, APIs are ordered by their effective path length, from longest to shortest.
- Effective path length counts all characters in the listen path except the characters inside dynamic segments such as
{id} or {id:regex}.
- Slashes count towards the total, so paths with more segments score higher than structurally equivalent paths with fewer segments.
- However, character length within static segments is the dominant factor. A long single-segment path outranks a short multi-segment path when the total character count is higher.
When two listen paths have the same effective length, the ordering between them is non-deterministic. Avoid deploying APIs with listen paths of identical effective length if they could overlap, as the routing outcome will be unpredictable.
/books/fiction (effective length 14) ranks above /books/{category} (effective length 7, since {category} is excluded)./users/{id}/profile (effective length 15) ranks above /users/{id} (effective length 7)./books/non-fiction (effective length 18) ranks above /books (effective length 6)./books/new-releases (effective length 19) ranks above /books/by/author (effective length 16), despite having fewer path segments.
Strict Routes
The http_server_options.enable_strict_routes configuration option prevents listen paths from matching requests that only share a common prefix. When enabled, Tyk Gateway performs an exact match against the listen path including the trailing /.
For example, with a listen path of /app:
- Strict Routes Enabled: matches
/app, /app/, and /app/* but not /app1/* or /apple/
- Strict Routes Disabled: all of the above match
Tyk recommends enabling exact path matching with strict routes for most use cases.
Dynamic Listen Paths
Listen paths support dynamic segments using the {paramName:regex} syntax. Tyk Gateway uses the regex constraint when matching the listen path, so the path will only match requests where the dynamic segment satisfies the constraint.
| Listen Path Pattern | Regular Expression Used in Match |
|---|
/users/{id}/profile/{type:[a-zA-Z]+} | ^/users/([^/]+)/profile/([a-zA-Z]+)$ |
/items/{itemID:[0-9]+}/details/{detail} | ^/items/([0-9]+)/details/([^/]+)$ |
/products/{productId}/reviews/{rating:\d+} | ^/products/([^/]+)/reviews/(\d+)$ |
/items/{itemID:[0-9]+}/details/{detail} matches /items/42/details/colour because 42 satisfies the [0-9]+ constraint, but does not match /items/widget/details/colour because widget does not.
A request that fails the constraint falls through to the next listen path in the ordered list rather than being rejected immediately.
The API ID Prefix
Tyk Gateway also registers every API at /{APIID}/ in addition to its configured listen path. This can be useful during development or in automation scripts where the API ID is already known from a management API response and a quick test call is needed without looking up the listen path. This prefix is not suitable for production traffic.
When a request arrives via /{APIID}/, strip_listen_path has no effect - the upstream receives the full path including the API ID rather than the stripped endpoint path. Use the configured listen path for all production routing.
Endpoint-Level Matching: URL Patterns
Once Tyk Gateway has identified the API definition, it compares the endpoint path against patterns defined in the API’s endpoint configuration. These patterns are treated as regular expressions.
Versioning
If the API uses URL path versioning, Tyk Gateway extracts the version identifier from the first path segment after the listen path before performing endpoint matching. See API Versioning for configuration detail.
Basic Patterns
A fixed pattern such as /users matches requests whose endpoint path is (or contains, depending on matching mode) that exact string.
Dynamic Path Parameters
Path parameters allow a pattern to match variable segments in the request path. Tyk Gateway converts each {paramName} into a capturing regex group (([^/]+)), which matches any non-slash sequence.
| Path Pattern | Regular Expression Used in Match |
|---|
/users/{id} | ^/users/([^/]+)$ |
/static/{path}/assets/{file} | ^/static/([^/]+)/assets/([^/]+)$ |
/orders/{orderId}/items/{itemId} | ^/orders/([^/]+)/items/([^/]+)$ |
| Wildcard | Matches |
|---|
{*} or * mid-path | one path segment, equivalent to a named parameter |
* end of path | remainder of path, including slashes |
/files/* matches both /files/report.pdf and /files/documents/report.pdf, whereas /files/{name} matches only /files/report.pdf.
Validating Path Parameters
Define parameter constraints in the OpenAPI parameter schema using standard fields such as type, pattern, format, and enum. Enable the Validate Request middleware to have Tyk Gateway enforce these constraints on incoming requests, rejecting any request where a parameter value does not match. Where multiple endpoints share the same path structure, Tyk Gateway also uses schema constraints to identify the correct endpoint.
For example, to accept only ULID values for the id parameter:
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: '^[0-7][0-9A-HJKMNP-TV-Z]{25}$'
path field of the extended paths entry rather than using {paramName} syntax. For example, to accept only ULID values:
"extended_paths": {
"track_endpoints": [
{
"path": "^/users/(?i)[0-7][0-9A-HJKMNP-TV-Z]{25}$",
"method": "GET"
}
]
}
When No Endpoint Matches
If a request matches the API’s listen path but no endpoint pattern in the API definition matches the request path, Tyk Gateway proxies the request upstream and applies only API-level middleware. Endpoint-specific middleware does not fire.
This default pass-through behavior means that paths not declared in the API definition are accessible unless explicitly restricted. Two middleware options control this:
- Allow List: Configures a list of permitted endpoint patterns. Any request that does not match an entry is rejected with
HTTP 403. This changes the default from allow-by-default to deny-by-default and is the recommended approach for locking down an API to only its declared endpoints. See Allow List.
- Block List: Configures a list of explicitly forbidden endpoint patterns. Matching requests are rejected with
HTTP 403; all other requests pass through. See Block List.
Matching Modes
The matching mode controls how Tyk Gateway anchors endpoint patterns when testing them against the request path. Tyk recommends enabling exact matching for most production use cases. In the default wildcard mode, a pattern such as /user matches not only /my-api/user but also /my-api/users and /my-api/groups/12/username/abc, which is rarely the intended behavior.
The mode is determined by two independent settings, which can be enabled in any combination:
| Mode | Prefix Setting | Suffix Setting | Pattern Matches On |
|---|
| Wildcard (default) | false | false | any substring of the path |
| Prefix | true | false | from the start of the path |
| Suffix | false | true | at the end of the path |
| Exact | true | true | the full path |
/user is anchored at both ends. Tyk Gateway tests the pattern against three path forms in sequence, accepting the first match:
- Endpoint path only:
/user
- Full path without version:
/listen-path/user
- Full path including listen path and version:
/listen-path/v4/user
In prefix mode, /user must appear at the start of the path but can be followed by anything, so it matches /user, /user/profile, and /user/123. Tyk Gateway tests against the same three path forms as exact mode.
In suffix mode, /user must appear at the end of the path, so it matches /my-api/user and /api/v2/user but not /my-api/user/profile.
In wildcard mode, /user can match anywhere in the path, including as a substring, so it also matches /my-api/users and /my-api/groups/12/username/abc.
Overriding the Matching Mode
The gateway-wide matching mode can be overridden for individual patterns using ^ and $ anchors in the pattern itself:
- Adding
^ to the start of a pattern applies prefix matching for that pattern, regardless of the global setting.
- Adding
$ to the end of a pattern applies suffix matching for that pattern, regardless of the global setting.
- Omitting the leading
/ suppresses prefix matching for that pattern, even if enabled globally.
If suffix matching is globally enabled, it cannot be disabled per-pattern. To achieve an explicit exact match in this case, write a full regular expression starting with ^/ and ending with $.
The following table shows the effective matching mode for combinations of gateway settings and pattern forms:
| Prefix Mode | Suffix Mode | Pattern | Effective Mode |
|---|
| ❌ | ❌ | /my-api/my-endpoint/{my-param} | wildcard |
| ✅ | ❌ | /my-api/my-endpoint/{my-param} | prefix |
| ❌ | ✅ | /my-api/my-endpoint/{my-param} | suffix |
| ✅ | ✅ | /my-api/my-endpoint/{my-param} | exact |
| ❌ | ❌ | ^/my-api/my-endpoint/{my-param} | prefix |
| ✅ | ❌ | ^/my-api/my-endpoint/{my-param} | prefix |
| ❌ | ✅ | ^/my-api/my-endpoint/{my-param} | exact |
| ✅ | ✅ | ^/my-api/my-endpoint/{my-param} | exact |
| ❌ | ❌ | /my-api/my-endpoint/{my-param}$ | suffix |
| ✅ | ❌ | /my-api/my-endpoint/{my-param}$ | exact |
| ❌ | ✅ | /my-api/my-endpoint/{my-param}$ | suffix |
| ✅ | ❌ | /my-api/my-endpoint/{my-param}$ | exact |
| ❌ | ❌ | ^/my-api/my-endpoint/{my-param}$ | exact |
| ✅ | ❌ | ^/my-api/my-endpoint/{my-param}$ | exact |
| ❌ | ✅ | ^/my-api/my-endpoint/{my-param}$ | exact |
| ✅ | ✅ | ^/my-api/my-endpoint/{my-param}$ | exact |
| ❌ | ❌ | my-api/my-endpoint/{my-param} | wildcard |
| ✅ | ❌ | my-api/my-endpoint/{my-param} | wildcard |
| ❌ | ✅ | my-api/my-endpoint/{my-param} | suffix |
| ✅ | ✅ | my-api/my-endpoint/{my-param} | suffix |
| ❌ | ❌ | /my-api/my-endpoint/* | wildcard |
| ✅ | ❌ | /my-api/my-endpoint/* | prefix |
| ❌ | ✅ | /my-api/my-endpoint/* | wildcard |
| ✅ | ✅ | /my-api/my-endpoint/* | prefix |
| ❌ | ❌ | my-api/my-endpoint/* | wildcard |
| ✅ | ❌ | my-api/my-endpoint/* | wildcard |
| ❌ | ✅ | my-api/my-endpoint/* | wildcard |
| ✅ | ✅ | my-api/my-endpoint/* | wildcard |
Protocol-Specific Matching
The matching behavior described above applies to standard HTTP APIs. Two protocols have specific requirements.
gRPC: The listen path must match the gRPC service name. gRPC method routing follows the path structure /{ServiceName}/{MethodName}, where the service name corresponds to the listen path. See gRPC Proxy for configuration detail.
TCP/TLS: Where multiple TCP APIs share the same port, Tyk Gateway uses Server Name Indication (SNI) to route connections to the correct API. See TCP Proxy for configuration detail.
Migrating Endpoint Patterns from Tyk Classic
The following behaviors are available in Tyk Classic endpoint patterns that cannot be carried over directly to Tyk OAS.
Routing vs. Validation Semantics: In Tyk Classic, the endpoint pattern is a regex applied at routing time. A request that does not match any endpoint pattern is not associated with that endpoint. Its middleware does not fire and the request is proxied upstream without error, with only API-level middleware applied. See When No Endpoint Matches.
In Tyk OAS, routing is determined by the path template structure. All requests matching the template shape reach the endpoint regardless of parameter values. To enforce parameter value constraints, you must enable the Validate Request middleware explicitly. A validation failure returns HTTP 422.
Path Patterns with No Template Equivalent: Some Tyk Classic regex patterns cannot be expressed as a single OpenAPI path template and require redesign. The most common case is alternation: a pattern such as ^/(users|groups)/[0-9]+$ matches two distinct path shapes and must be split into two separate operations in Tyk OAS.
Parameter Schema Anchoring: When migrating parameter constraints to a Tyk OAS parameter schema, note that the pattern field is not anchored by default. Without explicit ^ and $, a pattern matches any parameter value containing the expression rather than the full value. For example, [0-9]+ matches abc123 as well as 123. Write patterns as ^[0-9]+$ to enforce full-value matching. This is distinct from the routing-level anchoring described in Matching Modes, which applies equally to both Tyk OAS and Tyk Classic.
Regex Engine: Tyk Classic endpoint patterns use Go RE2. Although the OpenAPI Specification defines the pattern field as ECMA 262 regex, Tyk Gateway validates Tyk OAS patterns using Go RE2 as well. Lookaheads, lookbehinds, and backreferences are not available in either context.
Gateway Versions Prior to 5.0.14
Gateway-level configuration of URL path matching behavior was introduced in:
- Tyk Gateway 5.0.14
- Tyk Gateway 5.3.5
- Tyk Gateway 5.5.1
Prior to these versions, path matching was performed against the full request path in wildcard mode. To achieve prefix or suffix matching in older versions, write the endpoint pattern as a full regular expression. For example:
^/[^/]+/v4/json$ - exact match for any listen path with /v4/json below it^/listen-path/users - prefix match for a known listen path^/{*}/json - prefix match with a wildcard listen path segment
In versions prior to 5.0.14, an invalid regular expression in an endpoint pattern could cause unexpected matching behavior. Validate all regular expressions before deployment.
