marketplaces/docs/backend-platform/bootstrap-api-spec.md

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

{
  "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.