sdarbinyan
9cd56586fb
Some checks failed
Architecture Governance / architecture (push) Has been cancelled
Tenant subdomains route through api.<base-domain>; nginx forwards the exact storefront host derived from the validated browser origin.
56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
---
|
|
id: ADR-0004
|
|
title: Derive each API host from the complete storefront host
|
|
status: superseded
|
|
date: 2026-08-20
|
|
supersedes: []
|
|
tags: [architecture, multi-tenant, api, routing, dns]
|
|
superseded_by: [ADR-0005]
|
|
---
|
|
|
|
# ADR-0004: Derive each API host from the complete storefront host
|
|
|
|
> Superseded by [ADR-0005](ADR-0005-share-api-host-across-storefront-subdomains.md).
|
|
|
|
## 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>`.
|