Idempotent router(s) [draft]

[vitalik]

Problem Overview

The existing router system had several fundamental issues that prevented router reuse and caused unexpected behavior:

1. Routers are Single-Use

Once a Router is mounted to an API via api.add_router(), Router.api is set, making the router unusable with other APIs. Attempting to reuse a router raises ConfigError.

router = Router()
api1.add_router("/v1", router)  # Works
api2.add_router("/v2", router)  # Fails: "Router is already attached to API"

2. Mutation Leaks Through Decorators

When add_router() is called, decorators, auth, tags, and throttle settings are mutated directly on the router. These mutations persist and affect all future mounts:

router = Router()
api1.add_router("/v1", router, auth=auth1)  # router.auth = auth1
api2.add_router("/v2", router, auth=auth2)  # router.auth now auth2, but api1 uses same router!

3. Issue #1597: Child Routers Don't Inherit Decorators

Child routers added after parent mounting don't inherit parent's decorators because build_routers() was called at add_router() time, before children were fully configured.

4. URL Naming Clashes

Mounting the same router multiple times within one API produces duplicate URL names, causing Django URL resolution issues.