Introduction
Modern eCommerce applications rarely communicate directly with backend Java objects.
Instead, applications such as:
- Web storefronts
- Mobile applications
- React/Angular applications
- External systems
- Third-party applications
communicate with SAP Commerce through REST APIs.
In SAP Commerce, one of the most important technologies used for this purpose is:
OCC — Omni Commerce Connect
OCC exposes commerce functionality through RESTful web services. SAP's documentation describes the commercewebservices extension as exposing part of the Commerce Facades as RESTful web services, with the standard OCC web root being /occ/v2.
A simplified architecture looks like:
Mobile / Web / External System | | HTTP / REST ↓ OCC Controller | ↓ Facade | ↓ Service | ↓ DAO | ↓ FlexibleSearch | ↓ Database
Today we'll understand this complete flow and build a simple custom OCC API.
1. What is OCC?
OCC stands for:
Omni Commerce Connect
It provides REST APIs that allow external clients to interact with SAP Commerce.
For example:
GET /occ/v2/electronics/products/123
can retrieve product information.
Other common APIs include operations for:
- Products
- Carts
- Orders
- Customers
- Addresses
- Payment
- Promotions
- Catalogs
- Stores
SAP's OCC documentation lists resources such as Products, Carts, Orders, Users, Catalogs, Promotions and many others.
2. Why Do We Need OCC?
Imagine you have a mobile application.
The mobile application cannot directly call:
ProductService
because the mobile application is outside the SAP Commerce JVM.
Instead:
Mobile App | | HTTP ↓ SAP Commerce OCC | ↓ Facade | ↓ Service
The OCC layer provides the communication boundary.
3. OCC Architecture
A simplified SAP Commerce OCC architecture looks like:
CLIENT | HTTP / HTTPS Request | ↓ ┌──────────────┐ │ OCC Controller│ └───────┬──────┘ | ↓ ┌──────────────┐ │ Facade │ └───────┬──────┘ | ↓ ┌──────────────┐ │ Service │ └───────┬──────┘ | ↓ ┌──────────────┐ │ DAO │ └───────┬──────┘ | ↓ FlexibleSearch | ↓ DATABASE
On the response side:
Database ↓ Model ↓ Service ↓ Facade ↓ Data ↓ WsDTO ↓ JSON/XML ↓ Client
SAP specifically documents that data returned from commerce facades is converted to WsDTOs before being returned by the web service, helping isolate the API contract from commerce-layer data objects.
4. What is commercewebservices?
The main SAP Commerce extension responsible for OCC is:
commercewebservices
SAP documentation describes it as the main OCC extension built using Spring MVC.
It provides the infrastructure for:
- REST controllers
- Request handling
- DTO mapping
- Authentication
- Error handling
- Caching
- Request filters
- Web-service configuration
5. OCC URL Structure
A typical OCC v2 URL looks like:
/occ/v2/{baseSiteId}/...
For example:
/occ/v2/electronics/products/123
Here:
occ
is the OCC web context.
v2
is the API version.
electronics
is the base site.
SAP documents /occ/v2 as the standard web root for the commercewebservices extension.
6. OCC v1 vs OCC v2
This is an important interview topic.
SAP Commerce has both:
OCC v1 OCC v2
OCC v1 is the legacy implementation.
OCC v2 provides the newer default REST implementation and is designed around a stateless architecture.
For modern SAP Commerce development, you will generally encounter:
/occ/v2
7. GET, POST, PUT and PATCH
OCC APIs use standard HTTP methods.
GET
Used to retrieve information.
GET /occ/v2/electronics/products/123
POST
Usually used to create resources or trigger operations.
POST /occ/v2/electronics/users
PUT
Used for updates/replacements.
PUT /occ/v2/electronics/users/current/addresses/123
PATCH
Used for partial updates where supported.
SAP documents GET as primarily retrieving data and POST/PUT/PATCH as methods used for creating/updating resources in OCC.
8. Creating a Custom OCC API
Let's create a simple API:
GET /occ/v2/electronics/customproducts/{code}
The API should return product information.
Our architecture will be:
CustomProductController ↓ CustomProductFacade ↓ CustomProductService ↓ CustomProductDao ↓ FlexibleSearch
9. Create an OCC Extension
SAP Commerce provides the yocc extension template for creating an OCC extension. SAP's documentation states that OCC extension names should end with occ, for example xyzocc.
For example:
customocc
Add it to:
<extensions> ... <extension name="customocc"/> </extensions>
10. OCC Extension Structure
A simplified structure could look like:
customocc │ ├── src │ └── com.company.customocc │ └── controllers │ ├── resources │ └── occ │ └── v2 │ └── customocc │ ├── messages │ └── web │ └── spring │ └── extensioninfo.xml
SAP documents that OCC controller classes are located in the extension's /src directory and Spring configuration is located under the OCC web Spring resource path.
11. Create the Controller
Let's create:
@Controller @RequestMapping( value = "/{baseSiteId}/customproducts") public class CustomProductController { @Resource private CustomProductFacade customProductFacade; @GetMapping("/{code}") @ResponseBody public ProductWsDTO getProduct( @PathVariable final String code) { return customProductFacade.getProduct(code); } }
Now the API can be called using:
GET /occ/v2/electronics/customproducts/P100
SAP's OCC extension documentation demonstrates the same general approach: define a Spring MVC controller with @RequestMapping, expose methods for HTTP requests, and return a WsDTO.
12. What is @RequestMapping?
@RequestMapping maps an HTTP request to a controller.
For example:
@RequestMapping( value = "/{baseSiteId}/customproducts")
means requests matching:
/{baseSiteId}/customproducts
are routed to the controller.
Then:
@GetMapping("/{code}")
adds:
/{code}
So the complete URL becomes:
/occ/v2/electronics/customproducts/P100
13. What is @PathVariable?
Consider:
@GetMapping("/{code}") public ProductWsDTO getProduct( @PathVariable String code)
If the URL is:
/customproducts/P100
then:
code = P100
14. Create the Facade
The controller should not directly call the DAO.
Create:
public interface CustomProductFacade { ProductData getProduct(String code); }
Implementation:
public class DefaultCustomProductFacade implements CustomProductFacade { @Resource private ProductService productService; @Resource private ProductConverter productConverter; @Override public ProductData getProduct( final String code) { ProductModel product = productService.getProductForCode(code); return productConverter.convert(product); } }
Architecture:
Controller ↓ Facade ↓ Service
15. What is WsDTO?
A WsDTO is a Web Services Data Transfer Object used by OCC.
For example:
public class ProductWsDTO { private String code; private String name; }
The important distinction is:
ProductModel ↓ ProductData ↓ ProductWsDTO
The API should not expose your persistence model directly.
16. Why Not Return ProductModel?
Avoid:
public ProductModel getProduct(...)
from an OCC controller.
Reasons include:
- Tight coupling
- Internal data exposure
- Persistence concerns
- Security concerns
- API contract instability
- Serialization problems
Instead:
Model ↓ Data ↓ WsDTO
17. Converter and Populator
Converters and populators are important in SAP Commerce.
SAP recommends Spring-configured converters, with populators responsible for the actual conversion logic.
For example:
ProductModel ↓ ProductConverter ↓ ProductPopulator ↓ ProductData
18. Example Product Populator
public class CustomProductPopulator implements Populator<ProductModel, ProductData> { @Override public void populate( final ProductModel source, final ProductData target) { target.setCode(source.getCode()); target.setName(source.getName()); target.setDescription( source.getDescription()); } }
The converter invokes the configured populator pipeline.
19. WsDTO Mapping
OCC also has a mapping mechanism that maps commerce-layer data objects to Web Service DTOs.
SAP documents the DataMapper, FieldSetBuilder, and field-selection mechanisms used for OCC DTO mapping.
This is important because an API may not need to return every possible field.
For example:
BASIC DEFAULT FULL
can represent different levels of response detail depending on the configured API.
20. Example JSON Response
Our API could return:
{ "code": "P100", "name": "Laptop", "description": "Business Laptop" }
The client doesn't need to know that internally SAP Commerce used:
ProductModel
or:
FlexibleSearch
This is the benefit of the API abstraction.
21. OCC Request Flow
Let's trace the complete request.
Client sends:
GET /occ/v2/electronics/customproducts/P100
Step 1
Spring MVC receives the request.
HTTP Request ↓ OCC Controller
Step 2
Controller calls:
customProductFacade.getProduct("P100");
Step 3
Facade calls:
productService.getProductForCode("P100");
Step 4
Service retrieves the product.
Service ↓ DAO ↓ FlexibleSearch
Step 5
ProductModel is returned.
ProductModel
Step 6
Converter converts it:
ProductModel ↓ ProductData
Step 7
OCC converts the data to:
ProductWsDTO
Step 8
Spring serializes the DTO:
ProductWsDTO ↓ JSON
Final response:
{ "code": "P100", "name": "Laptop" }
22. Authentication in OCC
Security is an important part of OCC.
SAP Commerce OCC uses an OAuth2-based authentication mechanism in its documented implementation.
A typical flow is:
Client ↓ OAuth Token Request ↓ Access Token ↓ OCC API Request ↓ Authentication ↓ Authorization ↓ Controller
For example:
Authorization: Bearer <access-token>
23. OAuth2
Common OAuth-related scenarios include:
Client Credentials Password Grant
depending on the SAP Commerce version/configuration and security setup.
Current SAP Commerce documentation also exposes OAuth2 security definitions for OCC APIs.
24. Error Handling
A good OCC API shouldn't simply return:
500 Internal Server Error
for every problem.
For example:
Product doesn't exist
404 Not Found
Invalid request
400 Bad Request
Unauthorized
401 Unauthorized
Forbidden
403 Forbidden
Internal server problem
500 Internal Server Error
SAP provides specific OCC guidance around standardized error responses.
25. Validation
For POST/PUT/PATCH requests, request validation is particularly important.
For example:
@PostMapping public CustomerWsDTO createCustomer( @Valid @RequestBody CustomerWsDTO request) { ... }
Validation can ensure:
- Required fields
- Valid email
- Valid formats
- Valid business constraints
SAP notes that create/update OCC calls are commonly additionally validated within the OCC layer.
26. GET vs POST Example
GET
GET /occ/v2/electronics/products/P100
Purpose:
Retrieve product
POST
POST /occ/v2/electronics/users
Purpose:
Create customer
with:
{ "firstName": "John", "lastName": "Smith", "uid": "john@example.com" }
27. PUT Example
For an update:
PUT /occ/v2/electronics/users/current/addresses/123
Request body:
{ "firstName": "John", "lastName": "Smith", "town": "Hyderabad" }
28. PATCH
PATCH is useful when only part of a resource needs modification.
Conceptually:
PATCH /resource/123
instead of sending the complete resource.
Whether a specific OCC resource supports PATCH depends on the API implementation.
29. OCC Caching
Performance is extremely important for APIs.
SAP Commerce OCC supports caching for selected controller calls. SAP documents a local cache based on Ehcache for OCC.
Caching can help reduce:
Client ↓ Controller ↓ Facade ↓ Service ↓ DAO ↓ Database
for frequently requested data.
However, caching should be designed carefully for:
- Personalized data
- Customer-specific responses
- Cart data
- Pricing
- Inventory
- Frequently changing information
30. OCC and Stateless Architecture
OCC v2 is designed as a stateless REST API implementation.
This is important for scalability.
Conceptually:
Request 1 → Server A Request 2 → Server B Request 3 → Server C
The API shouldn't depend on a particular server maintaining application state between requests.
SAP's OCC v2 documentation specifically describes it as the default stateless implementation.
31. Swagger / API Documentation
Swagger is extremely useful when developing and testing OCC APIs.
Depending on your SAP Commerce setup, the interactive OCC documentation can be accessed through a Swagger UI endpoint.
SAP's documentation gives an example:
/rest/v2/swagger-ui.html
and explains that you can select a controller, choose an operation, provide parameters and execute the request directly from the documentation UI.
32. Testing OCC with Postman
Postman is another popular option.
Example:
Method: GET URL: https://localhost:9002/occ/v2/electronics/customproducts/P100
Headers:
Authorization: Bearer <token> Content-Type: application/json
Then click:
Send
Expected response:
{ "code": "P100", "name": "Laptop" }
33. Common OCC Mistakes
Mistake 1 — Calling DAO from Controller
Bad:
Controller ↓ DAO
Prefer:
Controller ↓ Facade ↓ Service ↓ DAO
Mistake 2 — Returning Model Directly
Avoid:
ProductModel
Use:
Data → WsDTO
Mistake 3 — Putting Business Logic in Controller
Keep controllers thin.
Mistake 4 — Returning Too Many Fields
Large responses increase:
- Network usage
- Serialization time
- Client processing
- API latency
Use appropriate field configuration.
SAP's configurable population and field-selection mechanisms exist partly to avoid unnecessary data conversion and payload size.
Mistake 5 — Ignoring Authentication
Never expose sensitive customer operations without proper authentication and authorization.
34. OCC Interview Questions
What is OCC?
OCC stands for Omni Commerce Connect and provides RESTful web services for SAP Commerce.
What is the default OCC v2 URL?
Typically:
/occ/v2
SAP documents this as the web root for the commercewebservices extension.
What is the difference between OCC and Facade?
Facade provides commerce-layer functionality through Data objects.
OCC exposes that functionality as REST APIs.
OCC ↓ Facade ↓ Service
Why do we use WsDTO?
To isolate the web-service API contract from internal commerce-layer data objects.
What is Converter?
Converter creates a target Data object and uses populators to populate it.
What is Populator?
Populator performs a specific part of the object-population process.
How does an OCC request flow?
Client ↓ Controller ↓ Facade ↓ Service ↓ DAO ↓ Database
Response:
Database ↓ Model ↓ Data ↓ WsDTO ↓ JSON/XML ↓ Client
How do you secure OCC?
Commonly through OAuth2 authentication and appropriate authorization/configuration.
How do you improve OCC performance?
Consider:
- Caching
- Pagination
- Efficient FlexibleSearch
- Avoiding N+1 calls
- Reducing response fields
- Configurable populators
- Avoiding unnecessary service calls
- Proper database indexes
35. Complete OCC Architecture to Remember
For interviews, remember this diagram:
CLIENT | | HTTP / HTTPS ↓ ┌──────────────────┐ │ OCC Controller │ └────────┬─────────┘ | ↓ ┌──────────────────┐ │ Facade │ └────────┬─────────┘ | ↓ ┌──────────────────┐ │ Service │ └────────┬─────────┘ | ↓ ┌──────────────────┐ │ DAO │ └────────┬─────────┘ | ↓ ┌──────────────────┐ │ FlexibleSearch │ └────────┬─────────┘ | ↓ DATABASE | ↓ ProductModel | ↓ Service | ↓ Facade | ↓ Converter | ↓ Populator | ↓ ProductData | ↓ WsDTO | ↓ JSON | ↓ CLIENT
Conclusion
OCC is one of the most important areas of SAP Commerce because it provides the REST API layer used by external clients and headless applications.
The key architecture is:
Client ↓ OCC Controller ↓ Facade ↓ Service ↓ DAO ↓ FlexibleSearch ↓ Database
And the response:
Database ↓ Model ↓ Service ↓ Facade ↓ Converter ↓ Populator ↓ Data ↓ WsDTO ↓ JSON/XML ↓ Client
Once you understand this flow, you can start designing your own custom OCC APIs instead of just consuming existing APIs.
No comments:
Post a Comment