Merging to release-5.7: [TT-12871, DX-1784] Add explanation of path ordering before pattern matching (#5812)

[buger]

User description

[TT-12871, DX-1784] Add explanation of path ordering before pattern matching (#5812)

---

PR Type

Documentation

---

Description

• Added a new "Path Ordering" section explaining Tyk's URL ordering logic.

• Detailed steps and rules for API and endpoint ordering.

• Included examples and references to RFC 3986 for clarity.

• Enhanced documentation to prevent routing to incorrect endpoints.

---

Changes walkthrough 📝

	Relevant files
Documentation	url-matching.md Added detailed documentation on path ordering and URL matching tyk-docs/content/getting-started/key-concepts/url-matching.md Added a new "Path Ordering" section with detailed steps. Included examples and rules for path ordering and matching. Clarified API request structure with RFC 3986 reference. Enhanced explanation for handling similar paths in URL matching. +25/-1

---

💡 PR-Agent usage: Comment /help "your question" on any pull request to receive relevant information

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅ 5812 - Fully compliant Fully compliant requirements: Add a new section on "Path ordering" to explain how Tyk orders APIs and endpoints before matching requests. Detail the steps and rules used for ordering, including handling of custom domains, path lengths, and dynamic segments. Include examples to clarify the ordering logic and its impact on routing. Enhance the explanation of the structure of API requests with a reference to RFC 3986 for better understanding. Improve documentation to help users avoid accidental routing to incorrect endpoints. Not compliant requirements:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Possible Ambiguity The explanation of path ordering rules may require further clarification, especially regarding the handling of dynamic segments and lexicographical ordering. Ensure the documentation is clear and unambiguous for all users. ## 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.

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Score
General	Specify that lexicographical order is case-sensitive to prevent misunderstandings Highlight that the lexicographical order is case-sensitive to avoid confusion for users who might assume otherwise. tyk-docs/content/getting-started/key-concepts/url-matching.md [118] -- For equal length paths, lexicographical order is applied - e.g. `/api/aba` before `/api/abc` +- For equal length paths, lexicographical order is applied (case-sensitive) - e.g. `/api/aba` before `/api/abc` Suggestion importance[1-10]: 8 Why: Highlighting that lexicographical order is case-sensitive is an important clarification, as it avoids potential misinterpretations by users who might assume otherwise. This addition enhances the accuracy of the documentation.	8
	Clarify that the path ordering logic applies to both static and dynamic paths Clarify the explanation of path ordering by explicitly stating that the ordering logic applies to both static and dynamic paths, as this distinction may not be immediately clear to all readers. tyk-docs/content/getting-started/key-concepts/url-matching.md [107-108] -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). +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, considering both static and dynamic paths. 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). Suggestion importance[1-10]: 7 Why: The suggestion improves clarity by explicitly stating that the ordering logic applies to both static and dynamic paths, which could prevent potential confusion for readers. This is a meaningful enhancement to the documentation.	7
	Reiterate that no further checks are performed after a match is found to stress the importance of path ordering Emphasize that no further checks are performed once a match is found, to ensure users understand the importance of the order. tyk-docs/content/getting-started/key-concepts/url-matching.md [120] -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. +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. Once a match is found, no further checks will be performed, so it is important to understand how Tyk orders the patterns to ensure there is no accidental routing to the wrong endpoint. Suggestion importance[1-10]: 6 Why: The suggestion emphasizes a critical aspect of the routing logic, ensuring users understand the significance of the order. While it reiterates an existing point, the rephrasing adds slight emphasis and improves readability.	6

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	0fa6e1b
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/677ba27e25e6990008115e0e
😎 Deploy Preview	https://deploy-preview-5864--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.