Initial draft

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](#pattern-ordering) is matched to requests.
 
 By fine-tuning these configurations, developers can create robust,
 secure, and maintainable routing rules tailored to their specific use
@@ -64,6 +65,12 @@ cases.
 
 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>://<host>/<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`.
 
 If a match is found, Tyk will then handle the request according to the configuration in the matching API definition. The *endpoint path* will be compared against any endpoints defined in the API definition to determine which endpoint-level configuration (such as transformation middleware) should be applied to the request.
@@ -95,6 +102,35 @@ 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.
 
+## Pattern ordering
+
+Before attempting to match the incoming request to the various APIs (and their endpoints) deployed on Tyk, we will first place all the endpoints in order before comparing the request against each in turn (according to the [matching rules](#pattern-matching) that have been defined). When a match is found between the request and a pattern, 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.
+
+Tyk's ordering algorithm takes into account:
+1. full path (including the host and any custom domain)
+2. alphanumeric order
+    - e.g. `/users/abc` before `/users/def`
+3. decreasing count of path fragments in the pattern (most to fewest)
+    - e.g. `/users/password/check` then `/users/password` then `/users`
+4. longest to shortest pattern (including host+listenPath+endpoint)
+    - to avoid matching a request to `/users/password-reset` to `/users/password`
+5. static patterns before dynamic
+    - e.g. `/users/admin/update` before `/users/{userId}/update`
+
+For example, if Tyk hosted APIs containing the following endpoints they would be ordered as shown, with requests matched against each in turn, starting from the top of the list, until a match was found. If no match is found, Tyk will return `HTTP 404 Not found`.
+
+| Pattern         | Description                          |
+|-----------------|--------------------------------------|
+| `https://tyk.my-host.com/test/abc/def` | Three path fragments, static pattern |
+| `https://tyk.my-host.com/status/{operationId}/active` | Three path fragments, dynamic pattern, 28 characters |
+| `https://tyk.my-host.com/status/{userId}/active` | Three path fragments, dynamic pattern, 23 characters |
+| `https://tyk.my-host.com/anything/access` | Two path fragments, static pattern |
+| `https://tyk.my-host.com/anything/{operationId}` | Two path fragments, dynamic pattern |
+| `https://tyk.my-host.com/test/abc` | Two path fragments, static pattern |
+| `https://tyk.my-host.com/test/{id}` | Two path fragments, dynamic pattern |
+| `https://tyk.my-host.com/anything` | One path fragment, static pattern, 9 characters |
+| `https://tyk.my-host.com/test` | One path fragment, static pattern, 5 characters |
+| `https://{customDomain}/test` | One path fragment, dynamic pattern, 5 characters |
 
 ## Pattern matching