79:T4a3,Before diving into routing strategies, we must establish a precise understanding of URL structure. Every HTTP request contains a **Request-URI** that follows a well-defined format specified in RFC 3986. The routing layer operates primarily on the **path** component, though sophisticated gateways may also consider query parameters, fragments, and even complete URIs. **The Anatomy of a URL:** ``` https://api.example.com:443/v2/users/123/orders?status=pending&limit=10#results └─┬──┘ └───────┬───────┘└┬┘ └─────────┬─────────┘ └──────────┬─────────┘ └──┬───┘ scheme authority port path query string fragment ``` For routing purposes, the **path** (`/v2/users/123/orders`) is the primary decision factor. It consists of: - **Path segments** separated by forward slashes - **Static segments** (`v2`, `users`, `orders`) that match literally - **Dynamic segments** (`123`) representing resource identifiers or parameters - **Optional trailing slashes** that may or may not be semantically significant7a:T4eb,The two fundamental matching strategies in path-based routing are **prefix matching** and **exact matching**. Understanding the semantics and trade-offs of each is essential for designing correct and maintainable routing configurations. **Exact Matching:** Exact matching requires the request path to match the routing rule *precisely*—no more, no less. ``` Rule: /api/users (exact) /api/users → MATCH ✓ /api/users/ → NO MATCH ✗ (trailing slash) /api/users/123 → NO MATCH ✗ (extra segment) /api/user → NO MATCH ✗ (different spelling) ``` Exact matching provides maximum precision but requires explicit rules for every distinct endpoint. It's ideal when you have a finite, well-defined set of endpoints and want to prevent unintended routing. **Prefix Matching:** Prefix matching routes any request whose path *starts with* the specified prefix. ``` Rule: /api/v2 (prefix) /api/v2 → MATCH ✓ /api/v2/ → MATCH ✓ /api/v2/users → MATCH ✓ /api/v2/users/123/orders → MATCH ✓ /api/v1/users → NO MATCH ✗ (different prefix) ``` Prefix matching is powerful for microservices architectures where an entire path subtree should route to a single service.7b:Tbb9,// Path parameter extraction implementation interface RouteParams { [key: string]: string; } interface RouteMatch { matched: boolean; params: RouteParams; remainingPath: string; } /** * Parse a route pattern into segments with metadata * Supports: static, :param, :param?, *wildcard, **glob */ function parseRoutePattern(pattern: string): RouteSegment[] { const segments: RouteSegment[] = []; const parts = pattern.split('/').filter(Boolean); for (const part of parts) { if (part.startsWith(':')) { const isOptional = part.endsWith('?'); const name = isOptional ? part.slice(1, -1) : part.slice(1); // Check for constraint: :id([0-9]+) const constraintMatch = name.match(/^(\w+)$(.+)$$/); segments.push({ type: 'param', name: constraintMatch ? constraintMatch[1] : name, optional: isOptional, constraint: constraintMatch ? new RegExp(`^${constraintMatch[2]}$`) : undefined, }); } else if (part === '*') { segments.push({ type: 'wildcard' }); } else if (part === '**') { segments.push({ type: 'glob' }); } else { segments.push({ type: 'static', value: part }); } } return segments; } /** * Match an incoming path against a parsed route pattern */ function matchRoute(pathSegments: string[], routeSegments: RouteSegment[]): RouteMatch { const params: RouteParams = {}; let pathIdx = 0; let routeIdx = 0; while (routeIdx < routeSegments.length) { const seg = routeSegments[routeIdx]; if (seg.type === 'static') { if (pathSegments[pathIdx] !== seg.value) { return { matched: false, params: {}, remainingPath: '' }; } pathIdx++; } else if (seg.type === 'param') { if (pathIdx >= pathSegments.length) { if (!seg.optional) { return { matched: false, params: {}, remainingPath: '' }; } } else { const value = pathSegments[pathIdx]; // Validate constraint if present if (seg.constraint && !seg.constraint.test(value)) { return { matched: false, params: {}, remainingPath: '' }; } params[seg.name] = value; pathIdx++; } } else if (seg.type === 'wildcard') { if (pathIdx >= pathSegments.length) { return { matched: false, params: {}, remainingPath: '' }; } pathIdx++; // Consume exactly one segment } else if (seg.type === 'glob') { // Glob captures all remaining segments params['**'] = pathSegments.slice(pathIdx).join('/'); pathIdx = pathSegments.length; } routeIdx++; } // Check if all path segments were consumed const matched = pathIdx === pathSegments.length; const remainingPath = pathSegments.slice(pathIdx).join('/'); return { matched, params, remainingPath }; } // Example usage: // Pattern: /users/:userId/orders/:orderId([0-9]+) // Path: /users/abc-123/orders/456 // Result: { matched: true, params: { userId: 'abc-123', orderId: '456' } }7c:T582,When a gateway has thousands of routing rules, the naive approach of iterating through each rule and checking for a match becomes prohibitively slow. Production gateways employ sophisticated data structures—primarily **tries** (prefix trees) and **radix trees**—to achieve O(path_length) routing regardless of the number of rules. **The Trie-Based Router:** A trie (pronounced "try") is a tree data structure where: - Each edge represents a path segment - Each node may contain routing metadata (backend, policies) - Traversal from root to leaf spells out a complete path pattern ``` [root] │ [api] / [v1] [v2] / \ [users] [orders] [users] │ / [:id] [:id] [search] │ │ [orders] [profile] ``` **Radix Tree Optimization:** A radix tree (compact prefix tree) compresses chains of single-child nodes into single edges, reducing memory usage and improving cache locality: ``` Trie: [a] → [p] → [i] → [/] → [v] → [1] Radix Tree: [api/v1] ``` Envoy proxy uses a **route table** with a combination of: 1. Static prefix indexing via radix trees 2. Linear regex matching for complex patterns 3. Priority ordering for ambiguity resolution7d:T1175,// Production-grade Trie-based Router interface TrieNode { children: Map>; paramChild?: TrieNode; // :param nodes paramName?: string; wildcardChild?: TrieNode; // * nodes globChild?: TrieNode; // ** nodes handler?: T; priority: number; } class TrieRouter { private root: TrieNode = { children: new Map(), priority: 0, }; /** * Insert a route pattern into the trie * Complexity: O(pattern_segments) */ insert(pattern: string, handler: T, priority: number = 0): void { const segments = pattern.split('/').filter(Boolean); let node = this.root; for (const segment of segments) { if (segment.startsWith(':')) { // Parameter segment if (!node.paramChild) { node.paramChild = { children: new Map(), priority: 0 }; } node.paramChild.paramName = segment.slice(1); node = node.paramChild; } else if (segment === '*') { if (!node.wildcardChild) { node.wildcardChild = { children: new Map(), priority: 0 }; } node = node.wildcardChild; } else if (segment === '**') { if (!node.globChild) { node.globChild = { children: new Map(), priority: 0 }; } node.globChild.handler = handler; node.globChild.priority = priority; return; // Glob terminates the pattern } else { // Static segment if (!node.children.has(segment)) { node.children.set(segment, { children: new Map(), priority: 0 }); } node = node.children.get(segment)!; } } node.handler = handler; node.priority = priority; } /** * Find the best matching route for a path * Complexity: O(path_segments) average case */ find(path: string): { handler: T; params: Record } | null { const segments = path.split('/').filter(Boolean); const matches: Array<{ handler: T; params: Record; priority: number }> = []; this.findRecursive(this.root, segments, 0, {}, matches); if (matches.length === 0) return null; // Return highest priority match (static > param > wildcard > glob) matches.sort((a, b) => b.priority - a.priority); return { handler: matches[0].handler, params: matches[0].params }; } private findRecursive( node: TrieNode, segments: string[], depth: number, params: Record, matches: Array<{ handler: T; params: Record; priority: number }> ): void { // Check for complete match if (depth === segments.length) { if (node.handler !== undefined) { matches.push({ handler: node.handler, params: { ...params }, priority: node.priority + 1000 // Exact match bonus }); } return; } const segment = segments[depth]; // Priority 1: Static match (highest priority) if (node.children.has(segment)) { this.findRecursive( node.children.get(segment)!, segments, depth + 1, params, matches ); } // Priority 2: Parameter match if (node.paramChild) { const newParams = { ...params, [node.paramChild.paramName!]: segment }; this.findRecursive(node.paramChild, segments, depth + 1, newParams, matches); } // Priority 3: Wildcard match if (node.wildcardChild) { this.findRecursive(node.wildcardChild, segments, depth + 1, params, matches); } // Priority 4: Glob match (captures remaining path) if (node.globChild && node.globChild.handler !== undefined) { const globPath = segments.slice(depth).join('/'); matches.push({ handler: node.globChild.handler, params: { ...params, '**': globPath }, priority: node.globChild.priority }); } } } // Usage example const router = new TrieRouter(); router.insert('/api/v1/users', 'user-list', 100); router.insert('/api/v1/users/:userId', 'user-detail', 90); router.insert('/api/v1/users/:userId/orders', 'user-orders', 80); router.insert('/static/**', 'static-files', 10); console.log(router.find('/api/v1/users')); // { handler: 'user-list', params: {} } console.log(router.find('/api/v1/users/123')); // { handler: 'user-detail', params: { userId: '123' } } console.log(router.find('/static/images/logo.png')); // { handler: 'static-files', params: { '**': 'images/logo.png' } }7e:T93d,// Priority calculation based on pattern specificity interface RouteRule { pattern: string; backend: string; explicitPriority?: number; } function calculatePriority(pattern: string): number { const segments = pattern.split('/').filter(Boolean); let priority = 0; for (let i = 0; i < segments.length; i++) { const segment = segments[i]; const positionWeight = (segments.length - i) * 10; // Earlier segments matter more if (segment === '**') { // Glob: lowest priority priority += positionWeight * 1; } else if (segment === '*') { // Wildcard: low priority priority += positionWeight * 2; } else if (segment.startsWith(':')) { // Parameter: medium priority priority += positionWeight * 5; } else { // Static: highest priority priority += positionWeight * 10; } } // Longer patterns generally more specific priority += segments.length * 5; return priority; } function resolveConflict(rules: RouteRule[], path: string): RouteRule | null { const matches = rules.filter(rule => matchPattern(rule.pattern, path)); if (matches.length === 0) return null; if (matches.length === 1) return matches[0]; // Sort by explicit priority first, then calculated priority matches.sort((a, b) => { const aPriority = a.explicitPriority ?? calculatePriority(a.pattern); const bPriority = b.explicitPriority ?? calculatePriority(b.pattern); return bPriority - aPriority; }); // Log if ambiguous (top two have same priority) const top = matches[0]; const second = matches[1]; const topPriority = top.explicitPriority ?? calculatePriority(top.pattern); const secondPriority = second.explicitPriority ?? calculatePriority(second.pattern); if (topPriority === secondPriority) { console.warn(`Ambiguous routing for ${path}:`, `${top.pattern} and ${second.pattern} have equal priority (${topPriority})`); } return top; } // Example: const rules: RouteRule[] = [ { pattern: '/api/users/:id', backend: 'user-service' }, { pattern: '/api/users/search', backend: 'search-service' }, { pattern: '/api/**', backend: 'legacy-api' }, ]; const match = resolveConflict(rules, '/api/users/search'); // Returns: { pattern: '/api/users/search', backend: 'search-service' } // Because static 'search' beats parameter ':id'7f:T4a2,Path-based routing in production requires addressing several operational concerns that don't surface in development: **1. Configuration Hot-Reloading** Routing rules change frequently. The gateway must support live configuration updates without dropping connections or causing traffic disruption. Production gateways use: - Graceful configuration draining (finish in-flight requests with old config) - Atomic configuration swaps - Configuration versioning with rollback capability **2. Routing Table Size Limits** Large routing tables impact: - Memory consumption (~100 bytes per rule for simple patterns, more for regex) - Startup time (parsing and compiling patterns) - Match latency (though well-optimized tries mitigate this) Most gateways support 10,000+ routes, but regex-heavy configurations may hit performance cliffs. **3. Security Implications** - **Path Traversal**: Ensure `/../` and encoded variants are normalized before routing - **Case Sensitivity**: Inconsistent case handling can bypass security rules - **Path Injection**: Validate that path parameters don't inject control characters - **Regex DoS**: Complex regex patterns can cause catastrophic backtracking71:{"json":{"id":"seed_c0efd168c742914d06d8d2d54d54fc3c","slug":"routing-and-traffic-management","category":"System Design (HLD)","topic":"Routing and Traffic Management","title":"Routing and Traffic Management","description":"Master the art of request routing at the API Gateway level. Learn path-based and header-based routing, request transformation patterns, traffic splitting strategies, and how to configure gateways for complex microservices architectures.","difficulty":"INTERMEDIATE","estimatedMinutes":90,"pages":[{"id":"seed_ab924fde703e0ac19a97e0da661ec262","title":"Path-Based Routing","order":0,"content":[{"id":"opening-hook","title":"The Routing Problem at Scale","content":[{"data":{"content":"Every request arriving at your API gateway carries a destination encoded in its URL path. The seemingly simple act of parsing `/api/v2/users/123/orders` and routing it to the correct backend service is, at scale, a complex algorithmic and architectural challenge. **Path-based routing** is the foundational mechanism that transforms a chaotic stream of incoming requests into organized, directed traffic flowing to the appropriate microservices.\n\nIn production systems handling millions of requests per second—systems like Netflix, Uber, and Stripe—the path-based routing layer must operate with sub-millisecond latency, support dynamic configuration updates without downtime, handle thousands of routing rules, and gracefully manage path conflicts and ambiguities. This page provides a Principal Engineer's perspective on path-based routing: the theoretical foundations, algorithmic implementations, and battle-tested production patterns."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"By the end of this page, you will understand path routing semantics deeply—from URL anatomy to trie-based routing algorithms. You'll master prefix vs. exact matching, path parameter extraction, wildcard patterns, routing priority resolution, and performance optimization techniques used in production gateways.","variant":"info"},"type":"callout"}]},{"id":"url-anatomy","title":"URL Anatomy and Routing Fundamentals","content":[{"data":{"content":"$79"},"type":"text"},{"data":{"icon":"Info","title":"Path Normalization Matters","content":"Before routing, gateways typically normalize paths: removing duplicate slashes (`//`), resolving dot segments (`/.` and `/..`), handling URL encoding (`%20` → space), and optionally adding or stripping trailing slashes. Inconsistent normalization is a common source of routing bugs and security vulnerabilities (path traversal attacks).","variant":"note"},"type":"callout"},{"data":{"content":"**The Routing Decision Model:**\n\nThe routing layer implements a function:\n\n```\nroute(path: string, method: string) → Backend | null\n```\n\nThis function must:\n1. Parse the incoming path into segments\n2. Match the path against a set of routing rules (patterns)\n3. Resolve conflicts when multiple rules match\n4. Extract path parameters from dynamic segments\n5. Return the target backend and any extracted parameters\n\nThe challenge lies in executing this function millions of times per second while supporting complex pattern matching and dynamic rule updates."},"type":"text"},{"data":{"rows":[["Static/Literal","/users","Exactly `/users`","Fixed API endpoints"],["Path Parameter","/:id or /{id}","Any single segment","Resource identifiers"],["Wildcard (*)","/files/*","Single segment (any)","Catch-all within level"],["Glob (**)","/proxy/**","Zero or more segments","Proxy/passthrough routes"],["Regex","/users/[0-9]+","Regex pattern match","Constrained parameters"],["Optional","/users/:id?","Segment may be absent","Optional trailing segments"]],"caption":"Path Segment Types in Routing Rules","headers":["Segment Type","Syntax Example","Matches","Use Case"]},"type":"table"}],"titleType":"number","titleNumber":1},{"id":"prefix-vs-exact","title":"Prefix Matching vs Exact Matching","content":[{"data":{"content":"$7a"},"type":"text"},{"data":{"left":[{"data":{"items":["**Precision**: Routes only explicitly defined paths","**Safety**: No unintended routing to services","**Maintenance**: Requires rule per endpoint","**Use Case**: Public APIs with strict contracts","**Example Config**: `path: /api/health` (exact)"],"title":{"icon":"Target","text":"Exact Matching","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}],"right":[{"data":{"items":["**Flexibility**: Routes entire path subtrees","**Simplicity**: Single rule for many endpoints","**Risk**: May route unintended paths","**Use Case**: Microservice path ownership","**Example Config**: `pathPrefix: /api/users`"],"title":{"icon":"Zap","text":"Prefix Matching","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}]},"type":"two-column"},{"data":{"icon":"AlertCircle","title":"The Trailing Slash Dilemma","content":"Whether `/users` and `/users/` are treated as the same path is configuration-dependent. RESTful conventions often treat them as different resources (collection vs. collection with sub-path). Your gateway must be explicit about trailing slash handling—either normalize them consistently or treat them as distinct. Ambiguity here causes subtle, hard-to-debug routing issues.","variant":"warning"},"type":"callout"},{"data":{"fileName":"nginx-routing-example.conf","languages":[{"code":"# Nginx location block matching semantics\n\n# Exact match (highest priority)\nlocation = /api/health {\n proxy_pass http://health-service;\n}\n\n# Prefix match (case-sensitive)\nlocation /api/v2/users {\n proxy_pass http://user-service;\n}\n\n# Prefix match with lower priority\nlocation /api/v2 {\n proxy_pass http://default-v2-service;\n}\n\n# Regex match (evaluated in order of appearance)\nlocation ~ ^/api/v[0-9]+/orders/[0-9]+$ {\n proxy_pass http://order-service;\n}\n\n# Precedence order:\n# 1. Exact match (=)\n# 2. Preferential prefix (^~)\n# 3. Regex (~ or ~*)\n# 4. Prefix match (longest match wins)","label":"Nginx","value":"nginx"},{"code":"# Kong declarative configuration\n_format_version: \"3.0\"\n\nservices:\n - name: user-service\n url: http://user-service:8080\n routes:\n # Strip path prefix before forwarding\n - name: user-api-route\n paths:\n - /api/v2/users\n strip_path: true\n path_handling: v1 # v0 = prefix, v1 = exact semantics\n \n - name: order-service\n url: http://order-service:8080\n routes:\n - name: order-api-route\n paths:\n - /api/v2/orders\n strip_path: true\n # Regex paths (requires Kong Enterprise or plugins)\n # paths:\n # - \"~/api/v[0-9]+/orders/.*\"","label":"Kong","value":"yaml"}]},"type":"code"}],"titleType":"number","titleNumber":2},{"id":"path-parameters","title":"Path Parameters and Dynamic Segments","content":[{"data":{"content":"RESTful APIs encode resource identifiers directly in the path: `/users/123`, `/orders/abc-456`, `/files/documents/report.pdf`. The gateway must **extract** these dynamic segments and either:\n\n1. Pass them as request headers to the backend\n2. Rewrite the path before forwarding\n3. Use them for routing decisions (e.g., sharding by user ID)\n\n**Parameter Syntax Conventions:**\n\nDifferent gateway technologies use varying syntax for path parameters:"},"type":"text"},{"data":{"rows":[["Express.js","`:param`","`/users/:userId`"],["Spring/JAX-RS","`{param}`","`/users/{userId}`"],["OpenAPI","`{param}`","`/users/{userId}`"],["Envoy","`:param` or regex","`/users/:id`"],["AWS ALB","Regex groups","`/users/(.*)`"]],"headers":["Gateway/Framework","Syntax","Example"]},"type":"table"},{"data":{"content":"**Parameter Constraints:**\n\nProduction systems often constrain parameters to specific patterns:\n\n```\n/users/{userId:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}}\n```\n\nThis regex constraint ensures `userId` matches UUID format, preventing invalid requests from reaching the backend."},"type":"text"},{"data":{"fileName":"path-parameter-extraction.ts","languages":[{"code":"$7b","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"icon":"Lightbulb","title":"Header Injection Pattern","content":"A common production pattern is for the gateway to extract path parameters and inject them as headers (e.g., `X-User-Id: 123`) before forwarding to backends. This decouples backends from URL structure—the backend reads headers instead of parsing URLs, enabling path restructuring without backend changes.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"routing-algorithms","title":"Routing Algorithm Internals","content":[{"data":{"content":"$7c"},"type":"text"},{"data":{"fileName":"trie-router.ts","languages":[{"code":"$7d","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"rows":[["Linear Scan","O(n × path_len)","O(n)","Yes","Small rule sets only"],["Hash Map (exact)","O(path_len)","O(n)","No","Health checks, static routes"],["Trie","O(path_len)","O(n × path_len)","Limited","Most gateways"],["Radix Tree","O(path_len)","O(n)","Limited","Envoy, high-perf systems"],["Hybrid (Radix + Regex)","O(path_len + m)","O(n)","Yes","Production gateways"]],"caption":"Routing Algorithm Complexity Comparison","headers":["Algorithm","Time Complexity (Match)","Space Complexity","Regex Support","Use in Production"]},"type":"table"}],"titleType":"number","titleNumber":4},{"id":"priority-resolution","title":"Priority and Conflict Resolution","content":[{"data":{"content":"When multiple routing rules match an incoming request, the gateway must deterministically select one. The **priority resolution strategy** is critical—ambiguous or incorrect resolution causes misdirected traffic, often silently.\n\n**The Conflict Scenario:**\n\nConsider these two rules:\n```\nRule A: /api/users/:id → user-service\nRule B: /api/users/search → search-service\n```\n\nRequest `/api/users/search` matches *both* rules:\n- Rule A: `:id` = \"search\"\n- Rule B: Exact match on \"search\"\n\nWhich wins? The answer depends on the gateway's resolution strategy.\n\n**Common Resolution Strategies:**"},"type":"text"},{"data":{"items":["**Specificity-Based** (Most Common): More specific patterns win. Static segments beat parameters beat wildcards beat globs. `/users/search` beats `/users/:id` beats `/users/*` beats `/**`.","**Longest Match**: The pattern that consumes the most path segments wins. Ties broken by specificity.","**Explicit Priority**: Each rule has a numeric priority. Highest priority wins regardless of pattern specificity.","**First Match**: Rules are evaluated in definition order; first match wins. Requires careful rule ordering.","**Most Recently Defined**: Last defined rule wins (rarely used, error-prone)."],"title":{"icon":"Target","text":"Priority Resolution Strategies","type":"icon","color":"primary","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"content":"**Production Best Practice: Explicit Priority with Logging**\n\nCombine specificity-based defaults with explicit priority overrides and conflict logging:\n\n```yaml\nroutes:\n # Explicit high priority for specific endpoints\n - path: /api/users/search\n priority: 100\n backend: search-service\n \n # Lower priority for parameterized routes \n - path: /api/users/:id\n priority: 50\n backend: user-service\n \n # Default catch-all with lowest priority\n - path: /api/**\n priority: 1\n backend: legacy-api\n```\n\nLog all ambiguous matches (where multiple rules have equal priority) to detect configuration issues before they cause incidents."},"type":"text"},{"data":{"icon":"AlertCircle","title":"Silent Routing Errors","content":"One of the most insidious production issues is silent misrouting—where requests go to the wrong service but still receive a \"valid\" response. For example, `/users/status` hitting a user detail endpoint with id=\"status\" and returning a 404. Monitor routing decisions with request tracing and validate routing tables in CI/CD.","variant":"error"},"type":"callout"},{"data":{"fileName":"priority-resolution-demo.ts","languages":[{"code":"$7e","label":"TypeScript","value":"typescript"}]},"type":"code"}],"titleType":"number","titleNumber":5},{"id":"path-rewriting","title":"Path Rewriting and Stripping","content":[{"data":{"content":"Routing is only half the story. After selecting a backend, the gateway often needs to **transform** the request path before forwarding. Common transformations include:\n\n1. **Path Stripping**: Remove the matched prefix\n2. **Path Prepending**: Add a prefix to the path\n3. **Path Replacement**: Completely replace the path\n4. **Regex-Based Rewriting**: Complex transformations\n\n**Path Stripping Example:**\n\n```\nIncoming: /api/v2/users/123\nRule: /api/v2/users → user-service (strip prefix)\nForwarded: /123 (prefix stripped)\n```\n\nThis pattern enables the gateway to \"own\" the API namespace (`/api/v2/users`) while backends receive root-relative paths.\n\n**Path Prepending Example:**\n\n```\nIncoming: /users/123\nRule: /users → legacy-api (prepend /v1/accounts)\nForwarded: /v1/accounts/users/123\n```\n\nThis enables API facade patterns where the public API differs from internal service paths."},"type":"text"},{"data":{"fileName":"path-rewrite-examples.yaml","languages":[{"code":"# Envoy route configuration with path rewriting\nroutes:\n - match:\n prefix: \"/api/v2/users\"\n route:\n cluster: user-service\n # Strip /api/v2/users prefix, keep the rest\n prefix_rewrite: \"/\" \n \n - match:\n prefix: \"/public/users\"\n route:\n cluster: user-service\n # Rewrite /public/users/123 → /internal/accounts/123\n regex_rewrite:\n pattern:\n google_re2: {}\n regex: \"^/public/users/(.*)\"\n substitution: \"/internal/accounts/\\1\"\n \n - match:\n safe_regex:\n google_re2: {}\n regex: \"^/api/v([0-9]+)/(.*)$\"\n route:\n cluster: versioned-api\n # Capture version and path, restructure\n regex_rewrite:\n pattern:\n google_re2: {}\n regex: \"^/api/v([0-9]+)/(.*)$\"\n substitution: \"/\\2?version=\\1\" # /api/v2/users → /users?version=2","label":"Envoy","value":"yaml"},{"code":"# AWS Application Load Balancer path pattern actions\n# Note: ALB has limited rewrite capabilities\n\n# Listener Rule 1: Forward with path pattern\n- Priority: 10\n Conditions:\n - Field: path-pattern\n Values:\n - \"/api/v2/users/*\"\n Actions:\n - Type: forward\n TargetGroupArn: !Ref UserServiceTargetGroup\n # ALB doesn't strip paths natively—must handle in target\n \n# For complex rewrites, use Lambda@Edge or CloudFront\n\n# CloudFront Function for path rewriting\n# (Attached to origin request)\nfunction handler(event) {\n var request = event.request;\n var uri = request.uri;\n \n // Strip /api/v2 prefix\n if (uri.startsWith('/api/v2')) {\n request.uri = uri.substring(7); // Remove first 7 chars\n }\n \n // Prepend internal path\n request.uri = '/internal' + request.uri;\n \n return request;\n}","label":"AWS ALB","value":"yaml"}]},"type":"code"},{"data":{"icon":"Lightbulb","title":"Debug Header for Path Transformations","content":"In non-production environments, inject a debug header showing the original and rewritten paths: `X-Original-Path: /api/v2/users/123` and `X-Rewritten-Path: /123`. This dramatically simplifies debugging routing issues.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":6},{"id":"production-considerations","title":"Production Considerations","content":[{"data":{"content":"$7f"},"type":"text"},{"data":{"type":"ordered","items":["**Validate Routes in CI/CD**: Parse and compile routing configuration in pipeline, catch syntax errors early","**Test Route Conflicts**: Automated tests for expected routing behavior, especially edge cases","**Monitor Route Latency**: Track P99 routing decision time; alert if trie traversal slows","**Log Unmatched Requests**: 404s should log the exact path for debugging","**Implement Rate Limiting per Route**: Different routes may have different limits","**Version Your Configuration**: Enable quick rollback of routing changes","**Document Route Ownership**: Which team owns which path prefix?","**Plan for Path Migration**: Strategy for changing path structure without breaking clients"],"title":{"icon":"CheckCircle","text":"Production Routing Checklist","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"icon":"AlertCircle","title":"The 'Works on My Machine' Trap","content":"Local gateway configurations often differ from production. Path matching behavior, case sensitivity, and trailing slash handling can vary between gateway versions and configurations. Always validate routing changes in a staging environment that mirrors production exactly.","variant":"warning"},"type":"callout"}],"titleType":"number","titleNumber":7},{"id":"summary","title":"Summary: Path-Based Routing Mastery","content":[{"data":{"content":"Path-based routing is the foundational mechanism that directs API traffic to appropriate backend services. Mastering it requires understanding URL anatomy, matching semantics, algorithmic implementations, and production operational concerns."},"type":"text"},{"data":{"type":"ordered","items":["**URL Structure**: Paths consist of static segments, parameters, wildcards, and globs—each with distinct matching semantics","**Exact vs Prefix**: Exact matching provides precision; prefix matching provides flexibility. Choose based on use case.","**Path Parameters**: Dynamic segments extracted by gateways enable resource-based routing and can be injected as headers","**Trie-Based Routing**: Production gateways use tries/radix trees for O(path_length) matching regardless of rule count","**Priority Resolution**: Conflicts are resolved by specificity, explicit priority, or rule order—know your gateway's strategy","**Path Rewriting**: Gateways transform paths (strip, prepend, regex rewrite) before forwarding to backends","**Production Concerns**: Hot-reload support, security normalization, and monitoring are essential for reliable routing"],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now have a deep understanding of path-based routing—from URL fundamentals to production-grade trie implementations. The next page covers header-based routing, which adds another dimension to routing decisions by considering HTTP headers, enabling sophisticated traffic management patterns.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":8}],"isLocked":false},{"id":"seed_d2025da710d3f07555784b525a1c4718","title":"Header-Based Routing","order":1,"content":null,"isLocked":true},{"id":"seed_6a59a94b6bdc3368b6f44499ecbda510","title":"Request Transformation","order":2,"content":null,"isLocked":true},{"id":"seed_88ad9b3041a4310d5cce3233564436bc","title":"Traffic Splitting","order":3,"content":null,"isLocked":true}]}}