marketplaces/docs/context/adrs/ADR-0004-derive-api-host-from-storefront-host.md

id, title, status, date, supersedes, tags

id	title	status	date	supersedes	tags
ADR-0004	Derive each API host from the complete storefront host	active	2026-08-20		architecture multi-tenant api routing dns

ADR-0004: Derive each API host from the complete storefront host

Context

One production bundle serves root domains and arbitrary storefront subdomains. The old bundle embedded api.dexarmarket.ru, while an earlier correction used a same-origin /backend gateway. Neither expresses the required domain rule: each storefront has a corresponding API hostname derived from its full host.

Examples:

• example.com uses api.example.com.
• store1.example.com uses api.store1.example.com.

Bootstrap, auth, legacy endpoints, and versioned endpoints must not use different base-host selection rules.

Decision

At runtime the frontend prefixes the complete browser hostname with api. and keeps the browser protocol: {protocol}//api.{hostname}.

• Bootstrap loads from https://api.{hostname}/bootstrap.
• Auth receives the same derived base through AUTH_API_URL.
• Legacy endpoints append their existing paths to that base.
• Versioned /api/... endpoints retain the /api prefix.
• Localhost and loopback continue to use the local /api development proxy.
• An explicit tenantApiBaseUrls entry may override the convention for an exceptional host, without changing the shared bundle.

The complete hostname is preserved. In particular, www.example.com maps to api.www.example.com; no label is stripped or interpreted by the frontend.

Consequences

One artifact works on root domains and nested storefront subdomains without a tenant allowlist or per-domain build. Every API hostname must have DNS, TLS, a working reverse proxy, and CORS configured for its corresponding storefront.

A wildcard such as *.example.com does not cover the multi-label hostname api.store1.example.com; nested API names need explicit certificates/DNS or a certificate and routing strategy that covers that depth. Backend tenant lookup must recognize api.<storefront-host> as the API alias of <storefront-host>.