Client Route

Client Route is the entry point where requests from clients enter the API Proxy. It is the gateway of the API Proxy to the outside world. Multiple relative paths can be defined for an API Proxy, providing dynamic routing support based on host, header, and method. This feature allows creating multiple API Proxies with the same relative path and performing dynamic routing between them based on host, header, or method information.

Client Route Features

Apinizer’s Client Route feature enables more flexible and dynamic routing of incoming requests in the API Gateway:

Multiple Paths

Multiple relative paths can be defined for an API Proxy

Host-Based Routing

Routing to different API Proxies based on host information

Header-Based Routing

Routing rules can be created based on HTTP header values

Method-Based Routing

Method-based routing can be performed

Before this feature was developed, only a single unique relative path could be defined for each API Proxy. With the new feature, multiple API 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 API Proxy.

Workflow

The following diagram shows how request and response flow occurs through the Gateway:

Routing Priority Order

The Gateway evaluates incoming requests according to the following priority order:

1. Relative Path

Highest priority

2. Hosts

Host header check

3. Headers

Header check

4. Methods

Lowest priority

Matching Logic

Hosts (OR Logic)

When multiple hosts are defined, it works with OR logic. That is, matching any one of the defined hosts is sufficient.

Example:

Hosts: hostname_x.com, hostname_y.com

If the Host header value in the request is hostname_x.com or hostname_y.com, the condition is met.

Headers (AND Logic)

When multiple headers are defined, it works with AND logic. That is, all defined headers must match.

Example:

Headers: testmode:true, test:true

Both testmode: true and test: true headers must be present in the request.

Path Matching

• Relative path matching has the highest priority
• More specific (longer) paths are evaluated before more general (shorter) paths
• If exact match is not found, the closest parent path is used

Method Matching

• Method check has the lowest priority
• If not specified, all HTTP methods are accepted

Wildcard Hostname Usage

Apinizer supports wildcard (joker character) usage in host definitions to provide flexibility. Wildcard hostnames allow all Host header values matching a specific pattern to meet the condition and thus match with the relevant Route.

Wildcard Rules

Wildcard 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

Matching Hosts:

• a.example.com
• x.y.example.com
• api.example.com
• test.subdomain.example.com

Right Side Wildcard

example.*

Matching Hosts:

• example.com
• example.org
• example.net
• example.io

Example Scenario

The following table shows 5 different API Proxies and their configured Client Route configurations:

This scenario will be used to understand the priority order and matching logic of Client Route.

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:

GET https://<ACCESS_URL>/jokes

Result: Routed to Proxy 5 (default proxy since no conditions are met)

Path matched but host and header conditions were not met, so Proxy 5 with the simplest configuration is selected.

Example 2: Host-Based Routing

Request:

GET https://<ACCESS_URL>/jokes
Host: hostname_x.com

Result: Routed to Proxy 2 (host condition met)

Proxy 2 is selected because host priority is higher than header.

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 provided)

Since headers work with AND logic, all headers must match. In case of missing headers, the next appropriate proxy is selected.

Example 4: Complete Header Match

Request:

GET https://<ACCESS_URL>/jokes
testmode: true
test: true

Result: Routed to Proxy 1 (all header conditions met)

Proxy 1 is selected because all header conditions are met.

Example 5: Path Priority - Basic Path

Request:

GET https://<ACCESS_URL>/jokes1

Result: Routed to Proxy 4 (exact path match)

Proxy 4 with exact matching path is selected because path priority is highest.

Example 6: Path Priority - Long Path

Request:

GET https://<ACCESS_URL>/jokes1/endpoint_x

Result: Routed to Proxy 3 (more specific path prioritized)

More specific (longer) paths are evaluated before more general (shorter) paths.

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)

If exact match is not found, the closest parent path is used.

Example 8: Path Match - Different Sub-path

Request:

GET https://<ACCESS_URL>/jokes1/endpoint_y

Result: Routed to Proxy 4 (parent path /jokes1 matched)

There is no exact match for /jokes1/endpoint_y path, so the parent path /jokes1 match is used.

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)

Since host priority is higher than header, when host condition is met, header conditions are ignored and Proxy 2 is selected.

Example 10: Different Path with Host and Header

Request:

GET https://<ACCESS_URL>/jokes1
Host: hostname_x.com
testmode: true
test: true

Result: Routed to Proxy 4 (path priority is highest, host and headers are ignored)

Since path priority is highest, when path match is met, host and header conditions are ignored.

Important Notes

Path Matching

• Relative path matching has the highest priority
• More specific (longer) paths are evaluated before more general (shorter) paths
• If 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 defined headers must be present in the request
• In case of missing or incorrect headers, proceed to the next appropriate proxy

Method Matching

• Method check has the lowest priority
• If not specified, all HTTP methods are accepted

Routing Combination Table

This table shows how the API Proxy is selected from the API Proxy’s perspective:

This table can be used as a reference to understand how Client Route evaluates different conditions.

Status	Description
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.

The Client Route feature allows you to easily manage complex routing scenarios in your API Gateway. By correctly understanding the priority order and matching logic, you can create flexible and powerful API routing configurations.

Next Steps

Client Route Settings

Configure Client Route settings

Routing and Upstream

Learn about Routing and Upstream concepts

HTTP Routing

HTTP Routing configuration

Message Processing and Policy Application

Learn about message flow and policy application process

What is API Proxy?

Learn about the API Proxy concept