[TT-12871, DX-1784] Add explanation of path ordering before pattern m…

…atching (#5812)

(cherry picked from commit f7ce399)

tyk-docs/content/getting-started/key-concepts/url-matching.md

@@ -54,6 +54,7 @@ Understanding the Gateway's URL path matching behavior is essential in scenarios
 - **API Versioning**: You may want to allow different versions of an API, such as `/v1/users` and `/v2/users`, while still matching certain common paths or endpoints.
 - **Middleware Control**: Middleware often relies on URL path matching to determine when specific behaviors, such as rate limiting or authentication, should be applied.
 - **Security Policies**: URL path matching ensures that security policies, such as allow or block lists, are enforced for the correct paths without mistakenly leaving critical routes unprotected.
+- **Similar paths**: If you deploy multiple APIs with similar paths (e.g. `/project` and `/project-management`) you will want to ensure that the [correct path](#path-ordering) is matched to requests.
 
 By fine-tuning these configurations, developers can create robust,
 secure, and maintainable routing rules tailored to their specific use
@@ -62,7 +63,13 @@ cases.
 
 ## Structure of the API request
 
-When a client makes a request to an API hosted on Tyk Gateway, they provide an HTTP method and *request path*. This *request path* will comprise the host (or domain) name for the Gateway, the API *listen path* and then (optionally) the *endpoint path*.
+When a client makes a request to an API hosted on Tyk Gateway, they provide an HTTP method and *request path*. This *request path* will comprise the host (or *domain*) name for the Gateway, the API *listen path* and then (optionally) the *endpoint path*.
+
+```
+<protocol>://<domain>/<listenPath>/<endpointPath>
+```
+
+With reference to [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) the `protocol` is the RFC's `scheme`, `host` is the `authority` and `listenPath/endpointPath` is the `path`.
 
 The *listen path* is a mandatory field defined in the API definition loaded onto the Gateway. Tyk will compare the incoming *request path* (after stripping off the host name) against all registered *listen paths* to identify the API definition (and hence Gateway configuration) that should be used to handle the request. If no match is found, then Tyk will reject the request with `HTTP 404 Not Found`.
 
@@ -95,6 +102,23 @@ If [URL path versioning]({{< ref "product-stack/tyk-gateway/advanced-configurati
 
 The remainder of the *request path* after any version identifier is considered to be the *endpoint path* (which may be simply `/`). When performing a match against endpoints configured in the API definition, Tyk treats the configured patterns as regular expressions, allowing advanced users to perform complex endpoint path matching by use of regexes in their API definitions.
 
+## Path Ordering
+
+Before attempting to [match](#pattern-matching) the incoming request to the various APIs deployed on Tyk to determine which route should be taken, Tyk will first place all the APIs in order. The order is important because the routing logic will compare the incoming request against each in turn until it finds a match (or returns `HTTP 404` if no match is found).
+
+The APIs loaded on the Gateway are ordered as follows:
+1. APIs that don't have a custom domain defined are moved to the end of the list.
+2. Then among each section (custom domain/no custom domain) it will sort by listen path length (longer paths first)
+    - Note that (dynamic) path parameters are not resolved at this stage so `/api/{category}/user` will rank higher than `/api/123/user`
+3. Then, for each listen path it will sort the endpoints using these rules:
+    - Remove path parameters (dynamic segments) in the listen path - for example `/{id}` will be replaced with `/`
+    - Order by the number of segments (count of `/`) from most to least - e.g. `/api/user/profile` before `/api/user`
+    - If two endpoints differ only by parameters, the non-parameterized goes first - e.g. `/api/user` before `/api/{userId}`
+    - If two endpoints have the same number of segments, the longer path goes first - e.g. `/api/user-access` before `/api/user`
+    - For equal length paths, lexicographical order is applied - e.g. `/api/aba` before `/api/abc`
+
+Having created the ordered list, Tyk will attempt to match the request against the paths (patterns) in the list, starting from the top and moving down the list. If a match is found, no further checks will be perfomed, so it is important to understand how Tyk orders the patterns to ensure there is no accidental routing to the wrong endpoint.
+
 
 ## Pattern matching