---
id: ADR-0004
title: Derive each API host from the complete storefront host
status: active
date: 2026-08-20
supersedes: []
tags: [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>`.