5.4 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.
/searchitems
Purpose:
- keyword-based product search for catalog/search pages.
High-level response shape:
- items array
- total count
Tenant rule:
- results must respect tenant catalog visibility and pricing policies.
/search/suggestions (future-ready)
Purpose:
- return instant search suggestions for typed keywords.
High-level response shape:
- suggestion strings or objects with label/value and optional popularity/count.
Tenant rule:
- suggestions generated only from tenant-visible catalog corpus.
/catalog/filters (future-ready)
Purpose:
- provide dynamic filter definitions and options for current search/category context.
High-level response shape:
- filter definitions
- option counts
- optional min/max ranges
Tenant rule:
- filter options/counts must be tenant-scoped and inventory-aware.
/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.
/me/wishlist (future-ready)
Purpose:
- authenticated wishlist synchronization across devices.
High-level response shape:
- wishlist product references
- optional addedAt metadata
Tenant rule:
- wishlist entries must remain tenant-scoped.
/me/compare (future-ready)
Purpose:
- optional compare list synchronization for authenticated users.
High-level response shape:
- compared product references
- optional addedAt metadata
Tenant rule:
- compare list must be isolated by tenant + user.
/me/saved-searches (future-ready)
Purpose:
- persist and restore saved search presets.
High-level response shape:
- saved query/filter/sort presets
- timestamps and id
Tenant rule:
- saved searches must be tenant-scoped and user-scoped.
/me/recently-viewed (future-ready)
Purpose:
- synchronize recently viewed product history for authenticated users.
High-level response shape:
- product references + viewedAt metadata
Tenant rule:
- history must remain tenant-scoped and privacy-safe.
/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