phase-11: add backend platform api specification and tenant resolution docs
This commit is contained in:
sdarbinyan
451
docs/architecture/backend/Backend-Platform-API-Spec.md
Normal file
451
docs/architecture/backend/Backend-Platform-API-Spec.md
Normal file
@@ -0,0 +1,451 @@
|
||||
# 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
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "1.0.0",
|
||||
"generatedAt": "2026-07-03T00:00:00Z",
|
||||
"tenant": { "id": "tenant-default-001", "slug": "default", "host": "default.local" },
|
||||
"branding": { "brandName": "Marketplace Platform Demo", "logoUrl": "/assets/images/dexar-logo.svg", "faviconUrl": "/favicon.ico" },
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"tenantId": "tenant-default-001",
|
||||
"branding": { "brandName": "Marketplace Platform Demo" },
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"branding": { "brandName": "Updated Brand" },
|
||||
"featureFlags": { "chat": true },
|
||||
"pages": []
|
||||
}
|
||||
```
|
||||
|
||||
### Example Response
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"id": "prod-001",
|
||||
"sku": "SKU-001",
|
||||
"title": "Demo Product",
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user