> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Proxy Client Route Usage Guide
> Flexible and dynamic routing of incoming requests in API Gateway with Client Route feature
# 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:
1. **Relative Path** (Highest priority)
2. **Hosts**
3. **Headers**
4. **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
```text theme={null}
*.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
```text theme={null}
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:///jokes
````
**Result:** Routed to Proxy 5 (default proxy since no condition is met)
#### Example 2: Host-Based Routing
**Request:**
```text theme={null}
GET https:///jokes
Host: hostname_x.com
```
**Result:** Routed to Proxy 2 (host condition met)
#### Example 3: Routing with Missing Header
**Request:**
```text theme={null}
GET https:///jokes
testmode: true
```
**Result:** Routed to Proxy 5 (Proxy 1 requires both headers, only one is provided)
#### Example 4: Full Header Match
**Request:**
```text theme={null}
GET https:///jokes
testmode: true
test: true
```
**Result:** Routed to Proxy 1 (all header conditions met)
#### Example 5: Path Priority - Basic Path
**Request:**
```text theme={null}
GET https:///jokes1
```
**Result:** Routed to Proxy 4 (exact path match)
#### Example 6: Path Priority - Long Path
**Request:**
```text theme={null}
GET https:///jokes1/endpoint_x
```
**Result:** Routed to Proxy 3 (more specific path takes priority)
#### Example 7: Path with Sub-Path
**Request:**
```text theme={null}
GET https:///jokes1/endpoint_x/endpoint_y
```
**Result:** Routed to Proxy 3 (closest parent path match)
#### Example 8: Path Match - Different Sub-Path
**Request:**
```text theme={null}
GET https:///jokes1/endpoint_y
```
**Result:** Routed to Proxy 4 (matched /jokes1 as parent path)
#### Example 9: Host and Header Combination
**Request:**
```text theme={null}
GET https:///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 |