Subdomain versioning

API Design

Meaning

Subdomain versioning assigns independent version numbers to distinct subdomains within a larger system so each can evolve at its own pace. It addresses the pain point of monolithic release cycles where a stable, slow-changing core domain is blocked by rapidly evolving supporting or generic subdomains. Teams reach for it when bounded contexts or microservices need to release independently without coupling their change cadence.

Primary Function

Release management

Communicative Purpose

Enables independent evolution of bounded contexts by decoupling version lifecycles across subdomains.

Pattern

assign version → scope to subdomain → publish compatibility contract → release on independent cadence

Função primária

Release management

Propósito comunicativo

Enables independent evolution of bounded contexts by decoupling version lifecycles across subdomains.

Situações de gatilho

Microservices architecture: coordinating releases across independently deployed services with different stability profiles

Contextos

Domain-driven design, microservices architectures, event-driven systems, strangler-fig migrations, polyrepo and monorepo setups with independent versioning

Padrão

assign version → scope to subdomain → publish compatibility contract → release on independent cadence

Colocados típicos

bounded context
semantic versioning
API gateway
contract testing
strangler fig pattern
independent deployment
compatibility window

Substituições comuns

Monolithic versioning (simpler but couples release cycles)
feature flags (faster toggling but does not isolate contracts)
blue-green deployment (handles traffic but not contract evolution)

Erros comuns

Versioning the entire system as one unit: causes unnecessary breaking changes for consumers of stable subdomains

Similar / contraste

Semantic versioning (operates at package or library level), API versioning (operates at endpoint level), database schema versioning (operates at data structure level)

Interferências

Coming from monolithic Java EE: may assume single WAR/EAR versioning — microservices require per-service version ownership. Coming from npm or Python packaging: may conflate package semver with subdomain semver — subdomain versioning spans runtime contracts, not just library APIs.

Família do chunk

bounded context
semantic versioning
strangler fig pattern
API versioning
contract testing

Nuance

When NOT to use: small systems with one team and tightly coupled components where independent versioning adds overhead without benefit. Performance: versioning overhead is minimal at the artifact level but can compound at the API gateway if routing rules multiply. Boundary conditions: subdomain versions must still respect upstream and downstream compatibility contracts; independent versioning does not mean independent compatibility.

Efeito pragmático

Reduces blast radius of changes, lets teams ship at their own cadence, and prevents stable subdomains from being dragged into unrelated release trains.

Dica de memória

Subdomain versioning is like giving each apartment in a building its own mailbox key — the landlord can renovate one floor without rekeying the whole building.

Upgrade path

Contract-driven versioning with Pact or Protobuf schema registries and automated compatibility gates in CI

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

# subdomain_versions.py SUBDOMAIN_VERSIONS = { "billing.core": "2.4.0", # core domain, slow-moving "billing.supporting": "5.12.1", # supporting, frequent changes "billing.generic": "1.0.3", # generic wrapper (e.g. notifications) } def deploy_subdomain(name: str, version: str) -> None: if name not in SUBDOMAIN_VERSIONS: raise ValueError(f"Unknown subdomain: {name}") SUBDOMAIN_VERSIONS[name] = version print(f"Deployed {name}@{version}") deploy_subdomain("billing.supporting", "5.13.0")

# gateway_router.py from typing import Callable class SubdomainRouter: def __init__(self) -> None: self.routes: dict[str, Callable[[str], str]] = {} def register(self, subdomain: str, version: str, handler: Callable[[str], str]) -> None: self.routes[f"{subdomain}@{version}"] = handler def route(self, subdomain: str, version: str, request: str) -> str: key = f"{subdomain}@{version}" if key not in self.routes: raise KeyError(f"No route for {key}") return self.routes[key](request) router = SubdomainRouter() router.register("orders.core", "3.1.0", lambda req: f"orders-core-3.1.0 handled: {req}") router.register("orders.supporting", "7.0.2", lambda req: f"orders-supporting-7.0.2 handled: {req}") print(router.route("orders.core", "3.1.0", "place-order"))

# contract_check.py def assert_compatible(upstream_version: str, downstream_version: str, min_upstream: str) -> None: upstream_major = int(upstream_version.split(".")[0]) min_major = int(min_upstream.split(".")[0]) if upstream_major < min_major: raise AssertionError( f"Downstream {downstream_version} requires upstream >= {min_upstream}, " f"got {upstream_version}" ) # orders.supporting@7.0.2 requires orders.core >= 3.0.0 assert_compatible("3.1.0", "7.0.2", "3.0.0") print("Contract satisfied")