Composable Storefront OCC Contract Hardening
How to keep Spartacus and custom composable storefronts stable while SAP Commerce OCC endpoints evolve behind them.
Composable Storefront projects stall when the frontend and SAP Commerce backend share assumptions informally. OCC contracts need explicit ownership, versioning, and regression tests. Without that, a checkout enhancement can break CMS rendering, price display, or cart restoration weeks later.
Own the Boundary#
The boundary is not just /occ/v2. It includes DTO fields, enum values, CMS component models, anonymous cart behaviour, user session rules, consent flow, cache headers, and error shapes.
| Contract surface | Typical failure | Control |
|---|---|---|
| Product details | Missing classification attributes | DTO snapshot tests |
| Cart | Promotion and delivery mode drift | Checkout journey replay |
| CMS | Component type mismatch | CMS model registry checks |
| User | Anonymous to registered cart merge | Auth state matrix |
| Search | Solr facet naming changes | Search response fixtures |
If the frontend team cannot name the backend owner for each surface, the contract is not hardened.
Stabilize DTO Extensions#
SAP Commerce teams often extend OCC DTOs quickly and leave the contract undocumented. Make extensions explicit and test them as API surface.
public class CciProductWsDTO extends ProductWsDTO {
private String merchandisingBadge;
private List<String> variantMerchandisingLabels;
public String getMerchandisingBadge() {
return merchandisingBadge;
}
}
The DTO is now a frontend dependency. Treat field removal, type changes, and nullability changes as breaking changes.
Version by Use Case#
Avoid one generic endpoint that tries to serve PDP, listing, cart, and recommendations. OCC responses should be sized for the route they support.
GET /occ/v2/{baseSiteId}/products/{code}?fields=FULL
GET /occ/v2/{baseSiteId}/products/{code}?fields=PDP
GET /occ/v2/{baseSiteId}/products/{code}?fields=LISTING
Field sets need ownership. A performance optimization that removes fields from FULL can become a production defect if Spartacus expects those fields on route activation.
Regression Harness#
Use route-level contract tests. Capture representative requests for PDP, PLP, cart, checkout, login, registration, and CMS page rendering. Replay them against the backend build before releasing the storefront.
Delivery Rule#
Composable Storefront succeeds when OCC behaves like a product interface, not an implementation detail. The contract should be documented, versioned, tested, and owned across backend and frontend release cycles.