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:
  • Special conversion between the DTOs and the models.
  • Here are the instructions; Customizing Resources and 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:
  • Custom Logic after or before the update (Cart) or custom URI path.
  • Here are the instructions; Customizing Resources and DTOs
• Commands: REST operation
  • Please read here to learn how to write your own commands: REST Commands Tutorial
  • Here are example of calling the commands: WebService API - Reference

• 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
  • Source: Key Features and Implementation Details

• 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/VariantAttributesConverter.java (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/PostCartToCarts.java (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/PutCartToCarts.java (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