152 lines
4.5 KiB
Markdown
152 lines
4.5 KiB
Markdown
# Bootstrap API Specification
|
||
|
||
## 1. Endpoint
|
||
- Method: `GET`
|
||
- Path: `/bootstrap`
|
||
- Auth: public (or optional lightweight token), tenant-scoped by domain
|
||
|
||
## 2. Domain-Based Request Flow
|
||
1. Receive request with host.
|
||
2. Resolve tenant by host.
|
||
3. Load tenant config aggregate from CONFIG DOMAIN.
|
||
4. Build versioned bootstrap payload.
|
||
5. Return public config JSON.
|
||
|
||
Failure responses:
|
||
- `404` unknown tenant domain
|
||
- `403` tenant inactive/suspended
|
||
- `500` config assembly failure
|
||
|
||
## 3. Production-Like Sample Response
|
||
```json
|
||
{
|
||
"schemaVersion": "2.1.0",
|
||
"generatedAt": "2026-07-05T10:30:00Z",
|
||
"tenant": {
|
||
"id": "a95c2f1b-58c1-4d8b-b35b-82e5bdf14321",
|
||
"slug": "alpha-market",
|
||
"code": "ALPHA",
|
||
"host": "shop.alpha.example.com",
|
||
"name": "Alpha Marketplace",
|
||
"defaultLocale": "en",
|
||
"supportedLocales": ["en", "ru", "hy"],
|
||
"defaultCurrency": "USD",
|
||
"supportedCurrencies": ["USD", "EUR", "AMD"],
|
||
"timezone": "UTC"
|
||
},
|
||
"theme": {
|
||
"themeId": "alpha-light",
|
||
"mode": "light",
|
||
"palette": {
|
||
"primary": "#2F6F6D",
|
||
"secondary": "#9FB8B6",
|
||
"accent": "#B5D7D4",
|
||
"textPrimary": "#1E3C38",
|
||
"textSecondary": "#5E7471",
|
||
"backgroundPrimary": "#FFFFFF",
|
||
"backgroundSecondary": "#F6F8F8",
|
||
"border": "#D7E0DF"
|
||
}
|
||
},
|
||
"layout": {
|
||
"type": "sidebar-left",
|
||
"options": {
|
||
"sidebarSticky": true,
|
||
"heroEnabled": true
|
||
}
|
||
},
|
||
"widgetRegistry": {
|
||
"manifestUrl": "/config/widgets/manifest.json"
|
||
},
|
||
"pages": [
|
||
{
|
||
"id": "page-home",
|
||
"key": "home",
|
||
"route": { "path": "/", "exact": true },
|
||
"layout": { "type": "carousel-home" },
|
||
"sections": [
|
||
{
|
||
"id": "sec-hero",
|
||
"type": "hero",
|
||
"order": 1,
|
||
"widgets": [
|
||
{
|
||
"id": "w-hero-main",
|
||
"type": "hero",
|
||
"version": "1.0.0",
|
||
"order": 1,
|
||
"padding": "0.5rem 0",
|
||
"visibility": { "desktop": true, "tablet": true, "mobile": true },
|
||
"props": { "title": "Welcome", "subtitle": "B2B Catalog" }
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"footer": {
|
||
"paymentIcons": [
|
||
{ "src": "/assets/payments/visa.svg", "alt": "Visa", "width": 40, "height": 28 },
|
||
{ "src": "/assets/payments/mastercard.svg", "alt": "Mastercard", "width": 40, "height": 28 }
|
||
],
|
||
"copyrightText": {
|
||
"en": "© 2026 Alpha Marketplace. All rights reserved.",
|
||
"ru": "© 2026 Alpha Marketplace. Все права защищены.",
|
||
"hy": "© 2026 Alpha Marketplace. Բոլոր իրավունքները պաշտպանված են:"
|
||
},
|
||
"legalPageKeys": ["about-us", "privacy-policy", "terms-of-service"]
|
||
},
|
||
"localization": {
|
||
"defaultLocale": "en",
|
||
"supportedLocales": ["en", "ru", "hy"],
|
||
"currencyByLocale": {
|
||
"en": "USD",
|
||
"ru": "USD",
|
||
"hy": "AMD"
|
||
}
|
||
},
|
||
"apiEndpoints": {
|
||
"bootstrap": { "path": "/bootstrap", "method": "GET", "timeoutMs": 5000 },
|
||
"website": {
|
||
"items": { "path": "/items", "method": "GET" },
|
||
"categories": { "path": "/categories", "method": "GET" },
|
||
"cart": { "path": "/cart", "method": "GET" },
|
||
"orders": { "path": "/orders", "method": "POST" },
|
||
"payments": { "path": "/payments", "method": "POST" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. Field-by-Field Meaning
|
||
- `schemaVersion`: bootstrap contract version used by frontend parser.
|
||
- `generatedAt`: payload generation timestamp.
|
||
- `tenant`: public tenant identity and locale/currency defaults.
|
||
- `theme`: UI tokens; no business logic.
|
||
- `layout.type`: global layout mode. Supported: `default`, `sidebar-left`, `carousel-home`, `minimal`.
|
||
- `widgetRegistry.manifestUrl`: source for widget definitions/components mapping metadata.
|
||
- `pages`: route-driven composition graph.
|
||
- `footer`: footer links/icons/legal references.
|
||
- `localization`: supported locales and currency mapping.
|
||
- `apiEndpoints`: public endpoint mapping for frontend clients.
|
||
|
||
## 5. Versioning Strategy
|
||
Use semantic versioning in `schemaVersion`:
|
||
- Patch (`2.1.1`): non-breaking metadata additions.
|
||
- Minor (`2.2.0`): additive fields/sections with backward compatibility.
|
||
- Major (`3.0.0`): breaking structural changes.
|
||
|
||
Operational rules:
|
||
- Keep old parser compatibility for at least one minor line.
|
||
- Publish migration notes for any major bump.
|
||
- Validate payload against schema before release.
|
||
|
||
## 6. Security Rules
|
||
Never include in bootstrap:
|
||
- private keys
|
||
- internal credentials
|
||
- admin secrets
|
||
- payment signing material
|
||
|
||
Bootstrap is strictly public runtime configuration.
|