119 lines
2.6 KiB
Markdown
119 lines
2.6 KiB
Markdown
# Business APIs
|
|
|
|
## 1. Scope
|
|
Business APIs provide transactional and catalog capabilities.
|
|
They must remain tenant-aware and must not return UI/layout/theme/widget configuration.
|
|
|
|
## 2. Immutable Rule
|
|
These APIs MUST NOT return:
|
|
- page composition
|
|
- layout mode
|
|
- widget metadata
|
|
- theme/footer/static page config
|
|
|
|
That data belongs to CONFIG DOMAIN (`/bootstrap`, `/pages/:slug`).
|
|
|
|
## 3. API Catalog
|
|
|
|
## /auth
|
|
Purpose:
|
|
- session creation/validation
|
|
- login/logout flows
|
|
- token refresh where applicable
|
|
|
|
High-level response shape:
|
|
- session/token metadata
|
|
- user identity claims
|
|
- permission scopes
|
|
|
|
Tenant rule:
|
|
- auth sessions are tenant-scoped by request context.
|
|
|
|
Must not change:
|
|
- authentication contract and downstream payment/auth integrations.
|
|
|
|
## /items
|
|
Purpose:
|
|
- list/fetch product items
|
|
- search/filter/sort
|
|
- item details and availability
|
|
|
|
High-level response shape:
|
|
- item arrays / item objects
|
|
- pagination metadata
|
|
- stock/price fields
|
|
|
|
Tenant rule:
|
|
- only items visible to tenant catalog policy.
|
|
|
|
Must not change:
|
|
- item identifiers/price semantics relied on frontend checkout/cart logic.
|
|
|
|
## /categories
|
|
Purpose:
|
|
- category tree retrieval
|
|
- category filtering metadata
|
|
|
|
High-level response shape:
|
|
- hierarchical or flat category collections
|
|
- visibility and ordering metadata
|
|
|
|
Tenant rule:
|
|
- category graph resolved per tenant catalog configuration.
|
|
|
|
Must not change:
|
|
- category IDs and parent linkage semantics consumed by frontend domain mapping.
|
|
|
|
## /orders
|
|
Purpose:
|
|
- create and track orders
|
|
- lifecycle state transitions
|
|
|
|
High-level response shape:
|
|
- order id
|
|
- status
|
|
- totals and line-items
|
|
|
|
Tenant rule:
|
|
- order creation/query restricted to tenant context.
|
|
|
|
Must not change:
|
|
- order status lifecycle contract integrated with payment and notification flows.
|
|
|
|
## /cart
|
|
Purpose:
|
|
- cart synchronization and server-side cart state where applicable
|
|
|
|
High-level response shape:
|
|
- cart items
|
|
- totals
|
|
- selected delivery/payment metadata
|
|
|
|
Tenant rule:
|
|
- cart state must be isolated by tenant + session/user.
|
|
|
|
Must not change:
|
|
- cart schema expected by checkout and payment request builders.
|
|
|
|
## /payments
|
|
Purpose:
|
|
- payment intent/QR/card flow initiation
|
|
- payment status querying
|
|
|
|
High-level response shape:
|
|
- payment id/reference
|
|
- redirect/QR links
|
|
- status fields
|
|
|
|
Tenant rule:
|
|
- payment credentials/routes resolved per tenant context on backend.
|
|
|
|
Must not change:
|
|
- existing payment provider contracts and callback/status semantics.
|
|
|
|
## 4. Governance for All Business APIs
|
|
- tenant derived from request context only
|
|
- strict repository-level tenant filtering
|
|
- no UI config payloads
|
|
- backward compatibility for existing frontend business flows
|