API Proxy Client Route User Guide

Apinizer's Client Route feature enables more flexible and dynamic routing of incoming requests in the API Gateway. This feature allows you to:

Define multiple relative paths for a single proxy
Route requests to different proxies based on host information
Create routing rules based on HTTP header values
Perform method-based routing

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 directs 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 of the defined hosts is sufficient.
Headers: When multiple headers are defined, it works with AND logic. That is, all defined headers must match.

Using Wildcard Hostnames

Apinizer supports the use of wildcards to provide flexibility in host definitions. Wildcard hostnames allow all Host header values that match a specific pattern to satisfy the condition and thus match the relevant Route.

Wildcard Rules

Wildcard hostnames must comply with the following rules:

The leftmost or rightmost label of the domain may contain only one asterisk (*)
The asterisk may be used at the beginning or end of the domain

Wildcard Examples

Left Side Wildcard

*.example.com

TEXT

This definition matches the following Host values:

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

Right Side Wildcard

example.*

TEXT

This definition matches the following Host values:

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

Sample Scenario

The table below shows 5 different proxies and their defined Client Route configurations.

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

Redirection Examples

Requests are routed as follows according to this configuration:

Example 1: Basic Routing

Request:

GET https://<ACCESS_URL>/jokes

TEXT

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

Example 2: Host-Based Redirection

Request:

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

TEXT

Result: Redirected to Proxy 2 (host condition met)

Example 3: Redirection with Missing Header

Request:

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

TEXT

Result: Redirected to Proxy 5 (Both headers are required for Proxy 1, only one was provided)

Example 4: Full Header Match

Request:

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

TEXT

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

Example 5: Path Precedence - Basic Path

Request:

GET https://<ACCESS_URL>/jokes1

TEXT

Result: Redirected to Proxy 4 (exact path match)

Example 6: Path Precedence - Long Path

Request:

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

TEXT

Result: Redirected to Proxy 3 (more specific path takes precedence)

Example 7: Path with Subpath

Request:

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

TEXT

Result: Redirected to Proxy 3 (closest parent path match)

Example 8: Path Matching - Different Subpath

Request:

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

TEXT

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

Example 9: Host and Header Combination

Request:

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

TEXT

Result: Redirected to Proxy 2 (host has higher priority than header)

Example 10: Host and Header with Different Path

Request:

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

TEXT

Result: Redirected to Proxy 4 (path has the highest priority, host and headers 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 an exact match cannot be found, the closest parent path is used.

Host Matching

Multiple hosts can be defined.
Hosts operate using 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, the next suitable proxy is used.

Method Matching

Method control 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 correctly understanding the priority order and matching logic, you can create flexible and powerful API routing configurations.

Routing Combination Table

None → Not found in the API proxy definition. The client's request is not checked.

Matches → Found in the API proxy definition. The client's request is checked and sent the expected value.

Does not match → Found in the API proxy definition. The client's request is checked and did not send the expected value.

#	HOST	PATH	METHOD	HEADER	RESULT	DESCRIPTION
1	None	None	None	None	✓ SELECTED	No criteria defined.
2	None	None	None	Matched	✓ SELECTED	All defined criteria matched (HEADER).
3	None	None	None	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
4	None	None	Matched	None	✓ SELECTED	All defined criteria matched (METHOD).
5	None	None	Matched	Matched	✓ SELECTED	All defined criteria matched (METHOD, HEADER).
6	None	None	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
7	None	None	Not Matched	None	✗ REJECTED	Routing cannot be performed because METHOD did not match.
8	None	None	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because METHOD did not match.
9	None	None	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because METHOD and HEADER did not match.
10	None	Matched	None	None	✓ SELECTED	All defined criteria matched (PATH).
11	None	Matched	None	Matched	✓ SELECTED	All defined criteria matched (PATH, HEADER).
12	None	Matched	None	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
13	None	Matched	Matched	None	✓ SELECTED	All defined criteria matched (PATH, METHOD).
14	None	Matched	Matched	Matched	✓ SELECTED	All defined criteria matched (PATH, METHOD, HEADER).
15	None	Matched	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
16	None	Matched	Not Matched	None	✗ REJECTED	Routing cannot be performed because METHOD did not match.
17	None	Matched	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because METHOD did not match.
18	None	Matched	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because METHOD and HEADER did not match.
19	None	Not Matched	None	None	✗ REJECTED	Routing cannot be performed because PATH did not match.
20	None	Not Matched	None	Matched	✗ REJECTED	Routing cannot be performed because PATH did not match.
21	None	Not Matched	None	Not Matched	✗ REJECTED	Routing cannot be performed because PATH and HEADER did not match.
22	None	Not Matched	Matched	None	✗ REJECTED	Routing cannot be performed because PATH did not match.
23	None	Not Matched	Matched	Matched	✗ REJECTED	Routing cannot be performed because PATH did not match.
24	None	Not Matched	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because PATH and HEADER did not match.
25	None	Not Matched	Not Matched	None	✗ REJECTED	Routing cannot be performed because PATH and METHOD did not match.
26	None	Not Matched	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because PATH and METHOD did not match.
27	None	Not Matched	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because PATH, METHOD, and HEADER did not match.
28	Matched	None	None	None	✓ SELECTED	All defined criteria matched (HOST).
29	Matched	None	None	Matched	✓ SELECTED	All defined criteria matched (HOST, HEADER).
30	Matched	None	None	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
31	Matched	None	Matched	None	✓ SELECTED	All defined criteria matched (HOST, METHOD).
32	Matched	None	Matched	Matched	✓ SELECTED	All defined criteria matched (HOST, METHOD, HEADER).
33	Matched	None	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
34	Matched	None	Not Matched	None	✗ REJECTED	Routing cannot be performed because METHOD did not match.
35	Matched	None	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because METHOD did not match.
36	Matched	None	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because METHOD and HEADER did not match.
37	Matched	Matched	None	None	✓ SELECTED	All defined criteria matched (HOST, PATH).
38	Matched	Matched	None	Matched	✓ SELECTED	All defined criteria matched (HOST, PATH, HEADER).
39	Matched	Matched	None	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
40	Matched	Matched	Matched	None	✓ SELECTED	All defined criteria matched (HOST, PATH, METHOD).
41	Matched	Matched	Matched	Matched	✓ SELECTED	All defined criteria matched (HOST, PATH, METHOD, HEADER).
42	Matched	Matched	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HEADER did not match.
43	Matched	Matched	Not Matched	None	✗ REJECTED	Routing cannot be performed because METHOD did not match.
44	Matched	Matched	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because METHOD did not match.
45	Matched	Matched	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because METHOD and HEADER did not match.
46	Matched	Not Matched	None	None	✗ REJECTED	Routing cannot be performed because PATH did not match.
47	Matched	Not Matched	None	Matched	✗ REJECTED	Routing cannot be performed because PATH did not match.
48	Matched	Not Matched	None	Not Matched	✗ REJECTED	Routing cannot be performed because PATH and HEADER did not match.
49	Matched	Not Matched	Matched	None	✗ REJECTED	Routing cannot be performed because PATH did not match.
50	Matched	Not Matched	Matched	Matched	✗ REJECTED	Routing cannot be performed because PATH did not match.
51	Matched	Not Matched	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because PATH and HEADER did not match.
52	Matched	Not Matched	Not Matched	None	✗ REJECTED	Routing cannot be performed because PATH and METHOD did not match.
53	Matched	Not Matched	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because PATH and METHOD did not match.
54	Matched	Not Matched	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because PATH, METHOD, and HEADER did not match.
55	Not Matched	None	None	None	✗ REJECTED	Routing cannot be performed because HOST did not match.
56	Not Matched	None	None	Matched	✗ REJECTED	Routing cannot be performed because HOST did not match.
57	Not Matched	None	None	Not Matched	✗ REJECTED	Routing cannot be performed because HOST and HEADER did not match.
58	Not Matched	None	Matched	None	✗ REJECTED	Routing cannot be performed because HOST did not match.
59	Not Matched	None	Matched	Matched	✗ REJECTED	Routing cannot be performed because HOST did not match.
60	Not Matched	None	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HOST and HEADER did not match.
61	Not Matched	None	Not Matched	None	✗ REJECTED	Routing cannot be performed because HOST and METHOD did not match.
62	Not Matched	None	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because HOST and METHOD did not match.
63	Not Matched	None	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HOST, METHOD, and HEADER did not match.
64	Not Matched	Matched	None	None	✗ REJECTED	Routing cannot be performed because HOST did not match.
65	Not Matched	Matched	None	Matched	✗ REJECTED	Routing cannot be performed because HOST did not match.
66	Not Matched	Matched	None	Not Matched	✗ REJECTED	Routing cannot be performed because HOST and HEADER did not match.
67	Not Matched	Matched	Matched	None	✗ REJECTED	Routing cannot be performed because HOST did not match.
68	Not Matched	Matched	Matched	Matched	✗ REJECTED	Routing cannot be performed because HOST did not match.
69	Not Matched	Matched	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HOST and HEADER did not match.
70	Not Matched	Matched	Not Matched	None	✗ REJECTED	Routing cannot be performed because HOST and METHOD did not match.
71	Not Matched	Matched	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because HOST and METHOD did not match.
72	Not Matched	Matched	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HOST, METHOD, and HEADER did not match.
73	Not Matched	Not Matched	None	None	✗ REJECTED	Routing cannot be performed because HOST and PATH did not match.
74	Not Matched	Not Matched	None	Matched	✗ REJECTED	Routing cannot be performed because HOST and PATH did not match.
75	Not Matched	Not Matched	None	Not Matched	✗ REJECTED	Routing cannot be performed because HOST, PATH, and HEADER did not match.
76	Not Matched	Not Matched	Matched	None	✗ REJECTED	Routing cannot be performed because HOST and PATH did not match.
77	Not Matched	Not Matched	Matched	Matched	✗ REJECTED	Routing cannot be performed because HOST and PATH did not match.
78	Not Matched	Not Matched	Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HOST, PATH, and HEADER did not match.
79	Not Matched	Not Matched	Not Matched	None	✗ REJECTED	Routing cannot be performed because HOST, PATH, and METHOD did not match.
80	Not Matched	Not Matched	Not Matched	Matched	✗ REJECTED	Routing cannot be performed because HOST, PATH, and METHOD did not match.
81	Not Matched	Not Matched	Not Matched	Not Matched	✗ REJECTED	Routing cannot be performed because HOST, PATH, METHOD, and HEADER did not match.