An HTTP API has grown paths like `/customers/7/orders/42/items/9001/discounts/3`. What problems does that depth create, and how would you restructure it?

## Why depth accumulates Deep URIs usually come from mirroring the database's foreign-key chain, or from adding one level at a time as the domain grows: first `/orders/{id}`, then items under orders, then discounts under items. Each step looks harmless. The result is a path where only the last one or two segments carry identity and the rest is decoration. ## What deep nesting actually costs **Addressability.** A URI is supposed to be a stable name for a resource. If naming a discount requires knowing its item, its order, and its customer, then a client that has only the discount id cannot construct the URL. Real clients hold ids — from a webhook, a log line, a stored reference — and now they need extra lookups just to build a request. **Stability under change.** URIs should survive domain changes that do not change the resource. Move a line item to a different order (a merge, a correction, a split shipment) and every deep URI beneath it changes, invalidating caches, bookmarks, stored references, and anything that logged the URL. The discount did not change; only its ancestry did. **Redundancy and consistency burden.** In `/customers/7/orders/42/items/9001`, the customer and order are already implied by item 9001. That means the server must either verify every segment for consistency — returning `404` when item 9001 is not in order 42, or order 42 not under customer 7 — or ignore them, in which case the URI can assert something false and two different URIs address the same resource. Verifying costs extra lookups on every request; ignoring costs correctness. **Route and test sprawl.** Every level of nesting multiplies routes: list, create, read, update, delete at each depth, each needing its own authorization and mismatch handling. The same logic gets reimplemented per level and drifts. **Ugly practical limits.** Long paths bump into URL length limits in proxies and logs, make access logs unreadable, and make API-gateway route matching and rate-limit rules harder to write. ## The restructuring rule **One level of nesting is the norm; two is the maximum; three is a smell.** Concretely: - Every resource that has a globally unique id gets a **canonical top-level URI**: `/order-items/9001`, `/discounts/3`. - Nesting is used for the two operations where the parent genuinely supplies context: **listing** a parent's children (`GET /order-items/9001/discounts`) and **creating** one (`POST /order-items/9001/discounts`, responding `201` with `Location: /discounts/3`). - Cross-cutting reads use the top-level collection with filters: `GET /discounts?orderId=42&status=active`. - The representation carries **links**, so a client that has an order does not need to know the path grammar to reach its items — it follows the URL you gave it. If child ids are only unique within the parent, you cannot fully flatten — `/orders/42/items/1` must keep its parent. In that case cap at that one level and give the *grandchildren* their own global ids so the chain stops there. ## Migration Because URIs are a contract, flattening usually means running both shapes for a while: keep the deep routes but answer them with `301`/`308` redirects to the canonical short URI, emit only the short form in every response body and `Location` header, and remove the deep routes once traffic to them has decayed. Log the old routes so you can tell when that is.