3.6 KiB
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.
/products/{id}/rating
Purpose:
- return product rating aggregate for engagement UI.
High-level response shape:
- average rating
- total reviews
- star distribution (5..1)
Tenant rule:
- aggregate must be computed only from tenant-visible reviews.
/products/{id}/reviews
Purpose:
- paginated review feed for product page.
High-level response shape:
- review list
- page/pageSize/total metadata
Tenant rule:
- only tenant-allowed and moderation-approved reviews.
/products/{id}/questions
Purpose:
- paginated questions and answers feed for product page.
High-level response shape:
- question list with answers
- page/pageSize/total metadata
Tenant rule:
- only tenant-visible questions/answers.
/products/{id}/reviews (POST)
Purpose:
- create review (rating/title/text/anonymous).
Must not change:
- request validation semantics expected by frontend engagement form.
/products/{id}/questions (POST)
Purpose:
- create product question (text/anonymous).
Must not change:
- acknowledgement contract expected by frontend engagement form.
/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