Easy REST

Easy REST extension enables developers to create REST API endpoints or incoming webhooks at runtime from the back-office without build and deployment.

Benefits

Easy REST extension provides the following benefits:

Create and configure REST services at runtime from Backoffice
Low code development based on Groovy
Can be automatically imported by ImpEx files

Features

Easy REST extension provides the following features:

REST service creation and configuration - Creation and configuration of the REST services from Backoffice in a programmatic way using low code (Groovy script)
Query parameters or path parameters - Supports both query string and path parameters to send parameters for GET requests
JSON or form URL encoded for POST requests - Supports both JSON (application/json) and FORM ( application/x-www-form-urlencoded) formats for create/update operations
CSRF - Supports Cross-Site Request Forgery protection
Authentication with OAuth 2.0 - Supports two modes of OAuth 2.0: Client ID for application or password for user
Authentication with Basic Auth - Supports basic authentication
Authentication with JWT - Supports authentication with JSON Web Token
Secret for incoming webhook - You can configure a token to your incoming webhook
Request validation - Validates the request on the service configuration and checks for the following errors (REST URL does not exist, Invalid HTTP method, Invalid data format and Permission denied)
Grouping - You can group Easy REST services together into an Easy REST services group
Swagger dynamic API documentation - Swagger is an Interface Description Language for describing REST APIs expressed using JSON. Swagger is used by Easy REST to generate automated Open API 3.0 documentation.
Caching - Provide various methods to cache the response and set server and client cache
Export to ImpEx - With a simple click from the Backoffice, you can export the Easy REST services definition

Getting started

Easy REST Service definition

Easy REST services can be configured from the backoffice or by ImpEx file.

INSERT_UPDATE EasyRest  ;Name[unique=true]  ;Path[unique=true]  ;SSL    ;Method(code)   ;Scope(code)    ;Format(code)   ;Script
                        ;testGET            ;testGET            ;true   ;GET            ;NONE           ;NONE           ;"log = org.slf4j.LoggerFactory.getLogger('easyrest');
log.info('parameters :' + parameters);
response.'body' = 'hello ' + parameters.firstname
return response"

Below is the data model of Easy Rest service.

Attributes	Comments
Name	Should be unique
Path	Path to build the publicly accessible URL (endpoint) for HTTP requests with the following format `http(s)://xxxx/easyrest/<path>`. The path can include path parameters, i.e `testPathParamters/{firstname}/{lastname}`. Should be unique and well-formed.
SSL	true/false
Method	HTTP Method such as GET/POST/PUT/PATCH/DELETE
Request format	Services can accept requests in different formats such as JSON(application/json), XML (application/xml), FORM (application/x-www-form-urlencoded) of the request. Note that format only affects operations with a request body, such as POST, PUT and PATCH. It is ignored for bodiless operations like GET.
Response content-type	Services can return response in different formats such as TEXT (text/plain), JSON (application/json), JSON (application/xml), HTML (text/html)
Permission scope	NONE (default), OAuth, Basic Auth
Secret	This is an optional free text field where you can put the secret or token of the webhook provider. This is recommended you store the secret here rather than directly in the Groovy script so you do not share the secret in non-production environment.
Groovy script	The Groovy script that processes the REST request or incoming webhook
Type	the Easy Rest service endpoint type. The default is `EASY_REST`. Additional endpoint types can be provided by additional extensions (e.g. EASY_REST_OCC for Easy REST OCC Service. `

Groovy script

The actual processing of the service is done by the Groovy script associated with the service.

The best way to understand how Easy REST API works is to check our test cases and the associated Groovy scripts that are self-explanatory: CX Boosters - Easy REST - Test Cases and projectdata_easyrest.impex inside easyrest extension of Easy Extension Framework.

This section describes how to retrieve request information and return a response.

Read request

The following variables are automatically set into the context of the Groovy script, so they can be accessed directly:

path - path to the REST service with the following format http(s)://xxxx/easyrest/<path>
headers - HTTP header from the request
secret - Such as set in the Easy REST service definition
parameters - Query string parameters for GET requests or URL encoded data for POST, PUT or PATCH requests
parametersValues - Query string parameters where values are stored as an array String array or URL encoded data for POST, PUT or PATCH requests
pathParameters - Path parameters
body - JSON object for “create” and “update” operations (POST, PUT, PATCH)

Below is an example of context.

{
    path=testPostJSON,
    header={content-length=43, host=localhost:9002, content-type=application/json, user-agent=curl/7.64.1, accept=*/*},
    secret=null,
    body={firstname=Yannick, lastname=Robin},
    parameters={}
}

Here is an example to get a parameter value in the Groovy script using parameters variable:

firstname = parameters.firstname

Here is an example to get a parameter value in the Groovy script using parametersValues variable:

firstname = parameters[0].firstname

Here is an example to get a path parameter value in the Groovy script using pathParameters variable:

firstname = pathParameters.firstname

Here is an example to get a parameter from the body in the Groovy script:

firstname = body.firstname

Send response

You should return a JSON with the following fields:

responseCode (optional, default: 200) - HTTP code of the response
headers (optional) - By default content-type is text/plain. You may want to replace by text/html, **application/json **...
body (optional, default: no value) - HTTP content of the response
stream (optional, default: no value) - HTTP content of the stream response

Here is a Groovy example to set a response:

response.'responseCode' = 200;
response.'body' = 'hello world!';
return response

Here is another example that sets the header:

response.headers = [
  'Access-Control-Allow-Origin' : '*'
];
return response

Error management

The framework validates requests based on the service configuration and checks for the following errors.

Error	HTTP Response Code
Invalid data format	HTTP 400 Bad Request
Invalid HTTP method	HTTP 400 Bad Request
Permission denied	HTTP 403 Permission denied
Service not found	HTTP 404 Not Found

You can also return your own applicative error based on the response code and response content returned by the Groovy script.

response.'responseCode' = 500;
response.'body' = 'This is my custom error message';
return response

Log management

easyrest is the default logger. You can activate the logs by changing its log level to INFO or DEBUG in ** local.properties** file

log4j2.logger.easyrest.level = DEBUG

You can log directly in the Groovy script using the following code:

log = org.slf4j.LoggerFactory.getLogger('easyrest');
log.info('body :' + body);

Swagger

Swagger is an Interface Description Language build around OpenAPI 3.0 for describing REST APIs expressed using JSON.

Swagger is used by Easy REST to generate automated documentation. Swagger UI can be used to explore the generated documentation and test services. By default, Swagger UI is available directly in the browser here: https://localhost:9002/easyrest/swagger-ui/. On SAP Commerce Cloud (CCv2), we use Backoffice property ccv2.services.backoffice.url.0 to build Swagger base URL. This is possible to override the base URL by updating the property easyrest.swagger.baseUrl. Here is an example:

easyrest.swagger.baseUrl=https://api.c65i60w-esapjnew1-d7-public.model-t.cc.commerce.ondemand.com

By default, each Easy REST service is documented with basic information. Below are the attributes to enrich swagger documentation.

Attribute	Comments	Example
Swagger Summary	An optional short summary of the operation
Swagger Description	An optional longer description of the operation
Swagger parameters	An optional entry in JSON format for describing parameters. See https://swagger.io/docs/specification/describing-responses/	`[ { "in" : "query" , "name" : "firstname" , "description" : "Your firstname" , "required" : true , "type" : "string" } ]`
Swagger request body	An optional entry in JSON format for describing body and form. See https://swagger.io/docs/specification/describing-request-body/ and https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject. This is typically used with “create” and “update” operations (POST, PUT, PATCH).	`{ "content" :{ "application/json" :{ "schema" :{ "type" : "object" , "properties" :{ "firstname" :{ "description" : "Your first name" , "type" : "string" }, "lastname" :{ "description" : "Your last name" , "type" : "string" } }, "required" :[ "firstname" ] } } } }`
Swagger responses	An optional entry in JSON format for describing responses. See https://swagger.io/docs/specification/describing-responses/	`{ "200": { "description" : "Hello message", "content" : { "text/plain" : { "schema" : { "type" : "string" } } }`

The OpenAPI definitions in JSON format is generated by an Easy REST service itself called 'swagger' and can be found here: https://localhost:9002/easyrest/swagger.

Security

SSL

If you deploy the webhook on Commerce Cloud with a valid certificate, the communication can be secured by HTTPS.

Whitelisting

On SAP Commerce Cloud, you can configure the whitelisting of the endpoint where you have deployed easyrest web application.

Incoming webhook token

Most webhook providers allow you to pass a secret or a “token” in every webhook request, so you can validate the sender. This secret is typically passed as an HTTP header, as a field in the JSON payload, or appended to the request URL. You can validate the webhook provider by checking in the Groovy script that the token you received is the one you expected.

Please note this method should be combined with SSL so the token is not transmitted in clear text.

Authentication Method

From Easy REST service configuration, you can activate the following authentication method:

NONE - For no authentication
OAuth - for two modes of OAuth 2.0 (Client ID for application or password for user)
Basic_Auth - for basic authentication
JWT - for JWT authentication

CSRF

You can activate Cross-Site Request Forgery protection from Easy REST service configuration.

Caching

Client caching

On the client send, you can configure the HTTP Cache-Control and Max-Age header directives.

HTTP Cache-Control accepts the following values:

NO_CACHE
NO_STORE
Private
Public

Server caching

On the server caching, you can set a time to live (TTL) in seconds. When TTL is configured to -1, there is no server caching.

Export to ImpEx

With a simple click from the Backoffice, you can export the Easy REST services definition:

From your Easy REST service editor, you click on Export button
From the export window, you can copy the generated ImpEx content into a file

Last modified: 18 August 2025