marketplaces/docs/architecture/backend/Backend-Platform-API-Spec.md

Backend Platform API Specification

Status: Draft for implementation handoff Date: 2026-07-03 Scope: Marketplace Platform (Website + Builder + Backoffice)

1. Tenant Resolution

Mechanism

• Backend resolves tenant from HTTP Host header.
• Frontend never sends tenant id or project key.
• Tenant resolution occurs before authorization and route handling.

Resolution Rules

1. Exact host match in tenant registry.
2. Alias host fallback.
3. Unknown host returns 404 tenant_not_found.

Validation

• Host must be present.
• Host must map to active tenant.
• Suspended tenant returns 403 tenant_suspended.

2. Bootstrap API

Endpoint

• Method: GET
• Path: /bootstrap

Purpose

• Return complete tenant runtime configuration for frontend bootstrap.

Authorization

• Public for website runtime.
• Optional authenticated extensions for builder/backoffice context may be included via claims.

Request

• Headers: Host (required)
• Query: locale (optional)

Response

• 200 with BootstrapConfig payload.

Validation

• Schema version required.
• Required segments: tenant, branding, theme, featureFlags, navigation, pages.

Example Response

{
  "schemaVersion": "1.0.0",
  "generatedAt": "2026-07-03T00:00:00Z",
  "tenant": { "id": "tenant-default-001", "slug": "default", "host": "default.local" },
  "branding": { "brandName": "Marketplace", "logoUrl": "/icons/icon-192x192.png", "faviconUrl": "/icons/icon-192x192.png" },
  "theme": { "themeId": "default-light", "mode": "light", "palette": { "primary": "#497671" }, "typography": { "primaryFontFamily": "DM Sans, sans-serif", "baseFontSize": 16 }, "spacing": { "unit": 4, "scale": [0,4,8] }, "borderRadiusScale": { "md": "12px" }, "shadows": { "md": "0 4px 12px rgba(0,0,0,0.15)" }, "iconSet": "default" },
  "featureFlags": { "wishlist": true, "reviews": true },
  "navigation": { "header": [], "footer": [] },
  "pages": []
}

3. Configuration API

Endpoint

• Method: GET
• Path: /configuration

Purpose

• Return complete editable configuration model for Builder.

Authorization

• Required: builder.read

Request

• Headers: Authorization bearer token

Response

• 200 configuration aggregate for tenant.

Validation

• Caller must belong to tenant context.
• Caller role must include builder permissions.

Example Response

{
  "tenantId": "tenant-default-001",
  "branding": { "brandName": "Marketplace" },
  "theme": { "themeId": "default-light" },
  "navigation": { "header": [], "footer": [] },
  "pages": []
}

4. Website API

Endpoint

• Method: GET
• Path: /website/pages/{pageKey}

Purpose

• Return website page composition for runtime rendering.

Authorization

• Public.

Request

• Path: pageKey required

Response

• 200 PageConfig with sections/widgets.

Validation

• pageKey must exist for tenant.
• hidden pages return 404.

Example Response

{
  "id": "page-home",
  "key": "home",
  "layout": "default-public",
  "sections": [
    {
      "id": "section-hero",
      "type": "hero",
      "order": 1,
      "widgets": [
        { "id": "widget-hero-main", "type": "hero", "version": "1.0.0", "props": { "title": "Welcome" } }
      ]
    }
  ]
}

5. Builder API

Endpoint

• Method: PUT
• Path: /builder/configuration

Purpose

• Save tenant configuration from Builder Sandbox.

Authorization

• Required: builder.write

Request

• Body: full or partial configuration document.

Response

• 200 updated configuration metadata.

Validation

• JSON schema validation.
• Widget types must be registered and supported.
• Route/path uniqueness checks.

Example Request

{
  "branding": { "brandName": "Updated Brand" },
  "featureFlags": { "chat": true },
  "pages": []
}

Example Response

{
  "version": 42,
  "updatedAt": "2026-07-03T12:00:00Z",
  "updatedBy": "user-100"
}

6. Backoffice API

Endpoint

• Method: GET
• Path: /backoffice/dashboard

Purpose

• Return dashboard aggregates for backoffice operations.

Authorization

• Required: backoffice.read

Request

• Optional query filters by date range.

Response

• KPIs and entity counts.

Validation

• Caller must belong to tenant.

Example Response

{
  "ordersToday": 14,
  "openOrders": 38,
  "products": 1024,
  "customers": 5600,
  "inventoryAlerts": 12
}

7. Products API

Endpoint

• GET /products
• GET /products/{id}
• POST /products
• PUT /products/{id}
• DELETE /products/{id}

Purpose

• Product catalog management for backoffice.

Authorization

• Read: backoffice.products.read
• Write: backoffice.products.write

Request

• Supports paging/filter/sort on GET /products.

Response

• Product entities aligned to UI contracts.

Validation

• SKU unique per tenant.
• Price and currency required.
• Visibility and status must be valid enum values.

Example Product

{
  "id": "prod-001",
  "sku": "SKU-001",
  "title": "Wireless Headphones",
  "price": { "amount": 149990, "currency": "RUB" },
  "stockStatus": "in_stock",
  "visible": true
}

8. Categories API

Endpoint

• GET /categories
• POST /categories
• PUT /categories/{id}
• DELETE /categories/{id}

Purpose

• Category tree management.

Authorization

• Read: backoffice.categories.read
• Write: backoffice.categories.write

Validation

• Category id unique.
• Parent relation must not create cycles.

Example Category

{
  "id": "cat-001",
  "title": "Electronics",
  "parentId": null,
  "itemsCount": 120,
  "visible": true
}

9. Orders API

Endpoint

• GET /orders
• GET /orders/{id}
• PATCH /orders/{id}/status

Purpose

• Order lifecycle tracking and updates.

Authorization

• Read: backoffice.orders.read
• Write: backoffice.orders.write

Validation

• Status transition must be legal according to state machine.

Example Response

{
  "id": "ord-1001",
  "status": "processing",
  "total": { "amount": 9900, "currency": "RUB" },
  "createdAt": "2026-07-03T10:20:00Z"
}

10. Media API

Endpoint

• POST /media/upload
• GET /media/{id}
• DELETE /media/{id}

Purpose

• Media asset management for products/widgets/pages.

Authorization

• Required: backoffice.media.write for upload/delete.

Validation

• File size/type constraints.
• Malware scan required before publish.

Example Response

{
  "id": "media-001",
  "url": "https://cdn.example.com/tenant-default/media-001.jpg",
  "mimeType": "image/jpeg"
}

11. Localization API

Endpoint

• GET /localization/dictionaries/{locale}
• PUT /localization/dictionaries/{locale}

Purpose

• Localization dictionary retrieval and updates.

Authorization

• Read: builder.localization.read
• Write: builder.localization.write

Validation

• Locale must be supported by tenant.
• Keys must be unique.

Example Response

{
  "locale": "ru",
  "version": "1.0.3",
  "entries": {
    "nav.home": "Главная",
    "nav.cart": "Корзина"
  }
}

12. Permissions API

Endpoint

• GET /permissions
• GET /roles
• PUT /roles/{role}

Purpose

• Permission definitions and role bindings.

Authorization

• Required: security.admin

Validation

• Role names unique.
• Permission keys must exist in definitions.

Example Response

{
  "definitions": [
    { "key": "builder.pages.edit" },
    { "key": "backoffice.products.read" }
  ],
  "roles": [
    { "role": "builder_admin", "permissions": ["builder.pages.edit"] }
  ]
}

13. Feature Flags API

Endpoint

• GET /feature-flags
• PUT /feature-flags

Purpose

• Tenant capability toggles for optional modules.

Authorization

• Read: builder.features.read
• Write: builder.features.write

Validation

• Flag keys must be from allowed registry.
• Non-boolean values rejected.

Example Response

{
  "wishlist": true,
  "compare": true,
  "reviews": true,
  "blog": false,
  "chat": false,
  "analytics": true,
  "notifications": true,
  "coupons": true,
  "loyalty": false,
  "giftCards": false,
  "invoices": true
}

Error Model (Common)

Structure

{
  "code": "validation_error",
  "message": "Validation failed",
  "details": [
    { "field": "pages[0].route.path", "message": "Path already exists" }
  ],
  "traceId": "trc-123"
}

Common Codes

• tenant_not_found
• tenant_suspended
• unauthorized
• forbidden
• validation_error
• conflict
• not_found
• internal_error

Contract Compatibility Note

Authentication, payment, and authorization behavior and contracts in the current system are preserved as-is. This document defines platform APIs around those stable integrations without changing their existing payload contracts.