Easy REST OCC | Easy Extension Framework

Benefits

Easy REST OCC Services are exposed under the OCC web extension with the same path prefix (e.g. /occ/v2/).
Spring MVC infrastructure provided by OCC extension can be used by Easy REST OCC Services. This includes :
- OCC contextual filters to contextualize the current Site, User, Cart, Language and Currency
- Orika mappers
- Message converters
- Error Handlers
Easy REST OCC Service Groovy scripts follow the same contract as standard Easy REST Services
Easy REST OCC Services are included in the OCC Swagger Documentation
Improved integration with Composable Storefront.

Installation

You need to add the easyrestocc extension to your SAP Commerce Cloud installation :

Creating a Basic Easy REST OCC Service

Basic Controller Class

Easy REST OCC Service can be implemented as Groovy script or Spring beans following the same contract as for standard Easy REST Services.

Below is an example of a Easy REST OCC Service controller Groovy class :

import com.sap.cx.boosters.easyrest.controller.EasyRestServiceController import javax.annotation.Resource import HelloWorldService class HelloWorldController implements EasyRestServiceController { @Resource HelloWorldService helloWorldService @Override Map execute(Map ctx) { def response = [:] response.'responseCode' = 200 response.'body' = groovy.json.JsonOutput.toJson([message: helloWorldService.sayHello(ctx.parameters.firstname)]) return response } }

Registering Easy REST OCC Service Bean

Easy REST OCC Service Beans are registered as an Easy Core Beans as follows :

easyCoreBeans { helloWorldService(HelloWorldService) } easyWebBeans('/occ') { helloWorldController(HelloWorldController) }

Easy REST Service Definition

Easy REST OCC Service are configured the same way as for standard Easy REST Services with the Type attribute equal to EASY_REST_OCC.

Additionally, the Path should match against the */easy/* pattern to be recognized as an Easy REST OCC endpoint.

INSERT_UPDATE EasyRest ;name[unique=true];easyRestGroup(name);path[unique=true];ssl;method(code);authenticationMethod(code);format(code);contentType(code);springBean;script;swaggerSummary;swaggerDescription;swaggerParameters[allownull=true];swaggerRequestBody[allownull=true];swaggerResponses[allownull=true];csrf;type(code) ; hello ;helloworld;easy/helloworld/hello;true;GET;NONE;NONE;JSON;helloWorldController;;;;"[ { ""in"":""query"", ""name"":""firstname"", ""description"":""Your firstname"", ""required"":true, ""schema"":{ ""type"":""string"", ""default"":""DEFAULT"" } } ]";;"{ ""200"": { ""description"" : ""Hello message"", ""content"" : { ""text/plain"" : { ""schema"" : { ""type"" : ""string"" } } } } }";false;EASY_REST_OCC

Swagger

The same configuration described for standard Easy REST Services Swagger apply to Easy REST OCC Services.

This allows to have a Swagger entry for each Easy REST OCC Service in the OCC Swagger located at https://<host>/occ/v2/swagger-ui/index.html.

Creatin a Custom Easy REST OCC Endpoint for Cart

As mentioned in the Benefits, Easy REST OCC services can rely on contextual data exposed in the endpoint URL to contextualize the current site, user, cart, language and currency.

In this section we will show how expose an additional cart endpoint implemented by an Easy REST OCC Service, to extend the OOTB CartsController.

Easy Cart Controller

The Groovy class below relies on the following components :

cartFacade: the Cart Facade to get the current Cart. The current Cart is resolved by the OCC extension based on the endpoint URL which encodes the baseSiteId, userId and cartId as path parameters.
dataMapper: The Orika Data Mapper to convert the cart data into dto based on the fields query parameter.

import com.sap.cx.boosters.easyrest.controller.EasyRestServiceController import de.hybris.platform.commercefacades.order.CartFacade import de.hybris.platform.commercewebservicescommons.dto.order.CartWsDTO import de.hybris.platform.webservicescommons.mapping.DataMapper import javax.annotation.Resource class EasyGetCartController implements EasyRestServiceController { @Resource CartFacade cartFacade @Resource(name = "dataMapper") private DataMapper dataMapper; @Override Map execute(Map ctx) { def response = [:] response.'responseCode' = 200 def cartData = cartFacade.getSessionCart() cartData.description = "Description from EasyRest OCC service" def fields = ctx.parameters.fields def cartDTO = dataMapper.map(cartData, CartWsDTO.class, fields) response.'body' = groovy.json.JsonOutput.toJson(cartDTO) return response } }

Easy Cart Service Definition

The following ImpEx is used to configure the Easy REST OCC Cart Service. Notice how the service path is defined ({baseSiteId}/users/{userId}/carts/{cartId}/easy) to support required path parameters and use the easy suffix to specify it is an Easy REST OCC service.

INSERT_UPDATE EasyRest ;name[unique=true];easyRestGroup(name);path[unique=true];ssl;method(code);authenticationMethod(code);format(code);contentType(code);springBean;script;swaggerSummary;swaggerDescription;swaggerParameters[allownull=true];swaggerRequestBody[allownull=true];swaggerResponses[allownull=true];csrf;type(code) ; easyGetCart ;helloworld;{baseSiteId}/users/{userId}/carts/{cartId}/easy;true;GET;NONE;NONE;JSON;easyGetCartController;;;;"[ { ""in"": ""path"", ""name"": ""baseSiteId"", ""description"": ""Base site identifier"", ""required"": true, ""schema"":{ ""type"":""string"" } }, { ""in"": ""path"", ""name"": ""userId"", ""description"": ""User identifier or one of the literals : 'current' for currently authenticated user, 'anonymous' for anonymous user"", ""required"": true, ""schema"":{ ""type"":""string"" } }, { ""in"": ""path"", ""name"": ""cartId"", ""description"": ""Cart identifier: cart code for logged-in user, cart GUID for anonymous user, or 'current' for the last modified cart."", ""required"": true, ""schema"":{ ""type"":""string"" } }, { ""in"": ""query"", ""name"": ""fields"", ""description"": ""Response configuration. This is the list of fields that should be returned in the response body. Examples: BASIC,DEFAULT,FULL"", ""required"": true, ""schema"":{ ""type"":""string"", ""default"":""DEFAULT"" } } ]";;"{ ""200"": { ""description"" : ""Cart"", ""content"" : { ""application/json"" : { ""schema"" : { ""type"" : ""string"" } } } } }";false;EASY_REST_OCC

After installing the Easy extension you should be able to test the endpoint in the Swagger UI :