Commerce Platform Web Services Extension: Key concepts and useful notes

Here are some key concepts and useful notes regarding this extension which complement the SAP Hybris documentation.


  • DTO: Pojo for the xml marshalling and unmarshalling of models. Hybris generates one for the model and another one for a collection of models\
    • Virtual properties which doesn't exists in the model can be defined. This concept is similar to the dynamic attributes of the models.
    • Virtual DTO which doesn't related to a model class can be created.
  • Reason to create your custom DTOs:
  • Resource: REST Controller with the CRUD operations. Hybris generates one for the requests with one model and a second one for those requests which work with a collection of models
  • Reason to create your custom Resources:
  • Commands: REST operation

Key Features

  • Caching
    • ETAG header. This is the default Jersey functionality and it reduces the bandwidth required for the requests. The workload is the same. It must be enabled.
    • The second Hybris caching strategy uses the If-Modified-Since HTTP header and it is inplemented.
    • The calculation of the ETAG can be expensive for complex responses.
    • A custom caching strategy could be implemented
  • Filtering of attributes (Attribute Selector)
    • Using query parameters or a property file a set of attributes of the resource may be returned.
    • The representation (detail or reference) of the complex attributes can be changed. The usefulness of this functionality is limited because only two levels of resources can be represented
  •  JSON:
    • Returns the body in JSON if the request contains the HTTP header Accept with the value application/json.
  • Localization: The header Accept-Language is used to determined the language.
  • Paging and Filtering of elements (Extended Collection)
    • Using query parameters the number of elements of collections and relations can be limited.
    • The number of elements returned per page may be random due to security constraints.
    • The filtering of relations allows a WHERE clause for the flexible search query. 
    • If the property given in *_sort doesn't exist in the elements, the whole object must be comparable.
  • Security
    • Each request must send the user and the password because RESTful services are stateless.
    • The user must be a member of the group webservicegroup when the hMC security strategy is turned on.
    • The read and change rights may be configurated using hMC (default) or property files.
    • It is possible to change the password or request a new one using REST.
  • Web Service Nature Ant Target:
    • It allows an extension to access all the DTOs and Resources in the platform
    • It creates a spring configuration to handle all the REST requests in the extension

Useful Tips

  • You can get the WADL using the url http://localhost:9001/trainingwebservices/rest/application.wadl where trainingwebservices is the name of your custom extension.
  • Virtual Resources and DTOs which aren't associated with a model go in the directory customextension/web/src. The spring bean definition of the virtual resource goes in customextension/resources/customextension-web-spring.xml
  • Custom Resources and custom DTOs which overwrite the ones generates by Hybris go in the directory customextension/custom/src
  • Customization of DTOs: Don't forget to add the platformwebservices extension as a dependency to your custom extension! If you forget and create the directory custom/src in your custom extension to overwrite a DTO, you will get the misleading error:
[yjavac] Compiling 2336 source files to /home/arobirosa/Documents/no_backup/hybris_certification/hybris/bin/ext-platform-optional/platformwebservices/web/webroot/WEB-INF/classes
 [yjavac] ----------
 [yjavac] 1. ERROR in /home/arobirosa/Documents/no_backup/hybris_certification/hybris/bin/ext-platform-optional/platformwebservices/web/src/de/hybris/platform/webservices/objectgraphtransformer/ (at line 64)
 [yjavac] dto.setVariantAttributes(targetVariantAttributes);
 [yjavac] ^^^^^^^^^^^^^^^^^^^^
 [yjavac] The method setVariantAttributes(List) is undefined for the type VariantProductDTO
 [yjavac] ----------
 [yjavac] ----------
 [yjavac] 2. ERROR in /home/arobirosa/Documents/no_backup/hybris_certification/hybris/bin/ext-platform-optional/platformwebservices/web/src/de/hybris/platform/webservices/resources/methods/ (at line 49)
 [yjavac] for (final CartEntryDTO entry : dto.getEntries())
 [yjavac] ^^^^^^^^^^^^^^^^
 [yjavac] Type mismatch: cannot convert from element type AbstractOrderEntryDTO to CartEntryDTO
 [yjavac] ----------
 [yjavac] ----------
 [yjavac] 3. ERROR in /home/arobirosa/Documents/no_backup/hybris_certification/hybris/bin/ext-platform-optional/platformwebservices/web/src/de/hybris/platform/webservices/resources/methods/ (at line 47)
 [yjavac] for (final CartEntryDTO entry : dto.getEntries())
 [yjavac] ^^^^^^^^^^^^^^^^
 [yjavac] Type mismatch: cannot convert from element type AbstractOrderEntryDTO to CartEntryDTO
 [yjavac] ----------
 [yjavac] 3 problems (3 errors)


  • The PUT and POST requests doesn't seem to support a JSON body. A 400  Bad Request error is generated and there isn't any consumes annotation allowing JSON requests in the abstractResource class.

–Based on SAP Hybris 6.7 und 5.3


Enter your comment. Wiki syntax is allowed: