API Proxy Client Route Usage Guide
Overview
Apinizer's Client Route feature enables more flexible and dynamic routing of incoming requests in the API Gateway. With this feature:
- Multiple relative paths can be defined for a proxy
- Routing can be done to different proxies based on host information
- Routing rules can be created based on HTTP header values
- Method-based routing can be performed
Before this feature was developed, only a single unique relative path could be defined for each proxy. With the new feature, multiple proxies with the same relative path can be created, and dynamic routing can be performed between them based on host, header, or method information.
How Does Client Route Work?
The Client Route feature evaluates incoming requests according to a specific priority order and routes them to the correct proxy.
Routing Priority Order
The Gateway evaluates incoming requests according to the following priority order:
- Relative Path (Highest priority)
- Hosts
- Headers
- Methods (Lowest priority)
Matching Logic
- Hosts: When multiple hosts are defined, it works with OR logic. That is, matching any one of the defined hosts is sufficient.
- Headers: When multiple headers are defined, it works with AND logic. That is, all defined headers must match.
Wildcard Hostname Usage
Apinizer supports wildcard (joker character) usage to provide flexibility in host definitions. Wildcard hostnames allow all Host header values that match a certain pattern to satisfy the condition and thus match the related Route.
Wildcard Rules
Wildcard hostnames must comply with the following rules:
- Can contain only one asterisk (*) in the leftmost or rightmost label of the domain
- Asterisk can be used at the beginning or end of the domain
Wildcard Examples
Left-Side Wildcard
*.example.com
This definition enables matching of the following Host values:
- a.example.com
- x.y.example.com
- api.example.com
- test.subdomain.example.com
Right-Side Wildcard
example.*
This definition enables matching of the following Host values:
- example.com
- example.org
- example.net
- example.io
## Example Scenario
The table below shows 5 different proxies and the Client Route configurations defined for them.
| Proxy ID | Relative Path | Methods | Hosts (OR) | Headers (AND) |
| -------- | ------------------- | ------- | -------------------------------- | ------------------------ |
| 1 | /jokes | \- | \- | testmode:true, test:true |
| 2 | /jokes | \- | hostname\_x.com, hostname\_y.com | \- |
| 3 | /jokes1/endpoint\_x | \- | \- | \- |
| 4 | /jokes1 | \- | \- | \- |
| 5 | /jokes | \- | \- | \- |
### Routing Examples
According to this configuration, incoming requests are routed as follows:
#### Example 1: Basic Routing
**Request:**
```text
GET https://<ACCESS_URL>/jokes
Result: Routed to Proxy 5 (default proxy since no condition is met)
Example 2: Host-Based Routing
Request:
GET https://<ACCESS_URL>/jokes
Host: hostname_x.com
Result: Routed to Proxy 2 (host condition met)
Example 3: Routing with Missing Header
Request:
GET https://<ACCESS_URL>/jokes
testmode: true
Result: Routed to Proxy 5 (Proxy 1 requires both headers, only one is provided)
Example 4: Full Header Match
Request:
GET https://<ACCESS_URL>/jokes
testmode: true
test: true
Result: Routed to Proxy 1 (all header conditions met)
Example 5: Path Priority - Basic Path
Request:
GET https://<ACCESS_URL>/jokes1
Result: Routed to Proxy 4 (exact path match)
Example 6: Path Priority - Long Path
Request:
GET https://<ACCESS_URL>/jokes1/endpoint_x
Result: Routed to Proxy 3 (more specific path takes priority)
Example 7: Path with Sub-Path
Request:
GET https://<ACCESS_URL>/jokes1/endpoint_x/endpoint_y
Result: Routed to Proxy 3 (closest parent path match)
Example 8: Path Match - Different Sub-Path
Request:
GET https://<ACCESS_URL>/jokes1/endpoint_y
Result: Routed to Proxy 4 (matched /jokes1 as parent path)
Example 9: Host and Header Combination
Request:
GET https://<ACCESS_URL>/jokes
Host: hostname_x.com
testmode: true
test: true
Result: Routed to Proxy 2 (host has higher priority than header)
Important Notes
Path Matching
- Relative path matching has the highest priority.
- More specific (longer) paths are evaluated before more general (shorter) paths.
- If an exact match is not found, the closest parent path is used.
Host Matching
- Multiple hosts can be defined.
- Hosts work with OR logic.
- If the host value in the request matches any of the defined hosts, the condition is met.
Header Matching
- Multiple headers can be defined.
- Headers work with AND logic.
- All headers defined in the request must be present.
- In case of missing or incorrect headers, it moves to the next suitable proxy.
Method Matching
- Method checking has the lowest priority.
- If not specified, all HTTP methods are accepted.
The Client Route feature allows you to easily manage complex routing scenarios in your API Gateway. By understanding the priority order and matching logic correctly, you can create flexible and powerful API routing configurations.
Routing Combination Table
None → Not present in the API proxy definition. What the client sends is not checked.
Matched → Present in the API proxy definition. What the client sends is checked, and it sent the expected value.
Not Matched → Present in the API proxy definition. What the client sends is checked, but it did not send the expected value.
This table shows from the API Proxy perspective how the API Proxy is selected.
| # | HOST | PATH | METHOD | HEADER | RESULT | EXPLANATION |
|---|---|---|---|---|---|---|
| 1 | None | None | None | None | ✓ SELECTED | No criteria defined |
| 2 | None | None | None | Matched | ✓ SELECTED | All defined criteria OK (HEADER) |
| 3 | None | None | None | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 4 | None | None | Matched | None | ✓ SELECTED | All defined criteria OK (METHOD) |
| 5 | None | None | Matched | Matched | ✓ SELECTED | All defined criteria OK (METHOD, HEADER) |
| 6 | None | None | Matched | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 7 | None | None | Not Matched | None | ✗ REJECTED | Cannot route because METHOD did not match |
| 8 | None | None | Not Matched | Matched | ✗ REJECTED | Cannot route because METHOD did not match |
| 9 | None | None | Not Matched | Not Matched | ✗ REJECTED | Cannot route because METHOD, HEADER did not match |
| 10 | None | Matched | None | None | ✓ SELECTED | All defined criteria OK (PATH) |
| 11 | None | Matched | None | Matched | ✓ SELECTED | All defined criteria OK (PATH, HEADER) |
| 12 | None | Matched | None | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 13 | None | Matched | Matched | None | ✓ SELECTED | All defined criteria OK (PATH, METHOD) |
| 14 | None | Matched | Matched | Matched | ✓ SELECTED | All defined criteria OK (PATH, METHOD, HEADER) |
| 15 | None | Matched | Matched | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 16 | None | Matched | Not Matched | None | ✗ REJECTED | Cannot route because METHOD did not match |
| 17 | None | Matched | Not Matched | Matched | ✗ REJECTED | Cannot route because METHOD did not match |
| 18 | None | Matched | Not Matched | Not Matched | ✗ REJECTED | Cannot route because METHOD, HEADER did not match |
| 19 | None | Not Matched | None | None | ✗ REJECTED | Cannot route because PATH did not match |
| 20 | None | Not Matched | None | Matched | ✗ REJECTED | Cannot route because PATH did not match |
| 21 | None | Not Matched | None | Not Matched | ✗ REJECTED | Cannot route because PATH, HEADER did not match |
| 22 | None | Not Matched | Matched | None | ✗ REJECTED | Cannot route because PATH did not match |
| 23 | None | Not Matched | Matched | Matched | ✗ REJECTED | Cannot route because PATH did not match |
| 24 | None | Not Matched | Matched | Not Matched | ✗ REJECTED | Cannot route because PATH, HEADER did not match |
| 25 | None | Not Matched | Not Matched | None | ✗ REJECTED | Cannot route because PATH, METHOD did not match |
| 26 | None | Not Matched | Not Matched | Matched | ✗ REJECTED | Cannot route because PATH, METHOD did not match |
| 27 | None | Not Matched | Not Matched | Not Matched | ✗ REJECTED | Cannot route because PATH, METHOD, HEADER did not match |
| 28 | Matched | None | None | None | ✓ SELECTED | All defined criteria OK (HOST) |
| 29 | Matched | None | None | Matched | ✓ SELECTED | All defined criteria OK (HOST, HEADER) |
| 30 | Matched | None | None | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 31 | Matched | None | Matched | None | ✓ SELECTED | All defined criteria OK (HOST, METHOD) |
| 32 | Matched | None | Matched | Matched | ✓ SELECTED | All defined criteria OK (HOST, METHOD, HEADER) |
| 33 | Matched | None | Matched | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 34 | Matched | None | Not Matched | None | ✗ REJECTED | Cannot route because METHOD did not match |
| 35 | Matched | None | Not Matched | Matched | ✗ REJECTED | Cannot route because METHOD did not match |
| 36 | Matched | None | Not Matched | Not Matched | ✗ REJECTED | Cannot route because METHOD, HEADER did not match |
| 37 | Matched | Matched | None | None | ✓ SELECTED | All defined criteria OK (HOST, PATH) |
| 38 | Matched | Matched | None | Matched | ✓ SELECTED | All defined criteria OK (HOST, PATH, HEADER) |
| 39 | Matched | Matched | None | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 40 | Matched | Matched | Matched | None | ✓ SELECTED | All defined criteria OK (HOST, PATH, METHOD) |
| 41 | Matched | Matched | Matched | Matched | ✓ SELECTED | All defined criteria OK (HOST, PATH, METHOD, HEADER) |
| 42 | Matched | Matched | Matched | Not Matched | ✗ REJECTED | Cannot route because HEADER did not match |
| 43 | Matched | Matched | Not Matched | None | ✗ REJECTED | Cannot route because METHOD did not match |
| 44 | Matched | Matched | Not Matched | Matched | ✗ REJECTED | Cannot route because METHOD did not match |
| 45 | Matched | Matched | Not Matched | Not Matched | ✗ REJECTED | Cannot route because METHOD, HEADER did not match |
| 46 | Matched | Not Matched | None | None | ✗ REJECTED | Cannot route because PATH did not match |
| 47 | Matched | Not Matched | None | Matched | ✗ REJECTED | Cannot route because PATH did not match |
| 48 | Matched | Not Matched | None | Not Matched | ✗ REJECTED | Cannot route because PATH, HEADER did not match |
| 49 | Matched | Not Matched | Matched | None | ✗ REJECTED | Cannot route because PATH did not match |
| 50 | Matched | Not Matched | Matched | Matched | ✗ REJECTED | Cannot route because PATH did not match |
| 51 | Matched | Not Matched | Matched | Not Matched | ✗ REJECTED | Cannot route because PATH, HEADER did not match |
| 52 | Matched | Not Matched | Not Matched | None | ✗ REJECTED | Cannot route because PATH, METHOD did not match |
| 53 | Matched | Not Matched | Not Matched | Matched | ✗ REJECTED | Cannot route because PATH, METHOD did not match |
| 54 | Matched | Not Matched | Not Matched | Not Matched | ✗ REJECTED | Cannot route because PATH, METHOD, HEADER did not match |
| 55 | Not Matched | None | None | None | ✗ REJECTED | Cannot route because HOST did not match |
| 56 | Not Matched | None | None | Matched | ✗ REJECTED | Cannot route because HOST did not match |
| 57 | Not Matched | None | None | Not Matched | ✗ REJECTED | Cannot route because HOST, HEADER did not match |
| 58 | Not Matched | None | Matched | None | ✗ REJECTED | Cannot route because HOST did not match |
| 59 | Not Matched | None | Matched | Matched | ✗ REJECTED | Cannot route because HOST did not match |
| 60 | Not Matched | None | Matched | Not Matched | ✗ REJECTED | Cannot route because HOST, HEADER did not match |
| 61 | Not Matched | None | Not Matched | None | ✗ REJECTED | Cannot route because HOST, METHOD did not match |
| 62 | Not Matched | None | Not Matched | Matched | ✗ REJECTED | Cannot route because HOST, METHOD did not match |
| 63 | Not Matched | None | Not Matched | Not Matched | ✗ REJECTED | Cannot route because HOST, METHOD, HEADER did not match |
| 64 | Not Matched | Matched | None | None | ✗ REJECTED | Cannot route because HOST did not match |
| 65 | Not Matched | Matched | None | Matched | ✗ REJECTED | Cannot route because HOST did not match |
| 66 | Not Matched | Matched | None | Not Matched | ✗ REJECTED | Cannot route because HOST, HEADER did not match |
| 67 | Not Matched | Matched | Matched | None | ✗ REJECTED | Cannot route because HOST did not match |
| 68 | Not Matched | Matched | Matched | Matched | ✗ REJECTED | Cannot route because HOST did not match |
| 69 | Not Matched | Matched | Matched | Not Matched | ✗ REJECTED | Cannot route because HOST, HEADER did not match |
| 70 | Not Matched | Matched | Not Matched | None | ✗ REJECTED | Cannot route because HOST, METHOD did not match |
| 71 | Not Matched | Matched | Not Matched | Matched | ✗ REJECTED | Cannot route because HOST, METHOD did not match |
| 72 | Not Matched | Matched | Not Matched | Not Matched | ✗ REJECTED | Cannot route because HOST, METHOD, HEADER did not match |
| 73 | Not Matched | Not Matched | None | None | ✗ REJECTED | Cannot route because HOST, PATH did not match |
| 74 | Not Matched | Not Matched | None | Matched | ✗ REJECTED | Cannot route because HOST, PATH did not match |
| 75 | Not Matched | Not Matched | None | Not Matched | ✗ REJECTED | Cannot route because HOST, PATH, HEADER did not match |
| 76 | Not Matched | Not Matched | Matched | None | ✗ REJECTED | Cannot route because HOST, PATH did not match |
| 77 | Not Matched | Not Matched | Matched | Matched | ✗ REJECTED | Cannot route because HOST, PATH did not match |
| 78 | Not Matched | Not Matched | Matched | Not Matched | ✗ REJECTED | Cannot route because HOST, PATH, HEADER did not match |
| 79 | Not Matched | Not Matched | Not Matched | None | ✗ REJECTED | Cannot route because HOST, PATH, METHOD did not match |
| 80 | Not Matched | Not Matched | Not Matched | Matched | ✗ REJECTED | Cannot route because HOST, PATH, METHOD did not match |
| 81 | Not Matched | Not Matched | Not Matched | Not Matched | ✗ REJECTED | Cannot route because HOST, PATH, METHOD, HEADER did not match |