====== 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. ===== Concepts ===== * 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; [[https://help.sap.com/viewer/d0224eca81e249cb821f2cdf45a82ace/6.7.0.0/en-US/8ba18055866910148762dbface2357aa.html|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; [[https://help.sap.com/viewer/d0224eca81e249cb821f2cdf45a82ace/6.7.0.0/en-US/8ba18055866910148762dbface2357aa.html|Customizing Resources and DTOs]] * Commands: REST operation * Please read here to learn how to write your own commands: [[https://help.sap.com/viewer/d0224eca81e249cb821f2cdf45a82ace/6.7.0.0/en-US/8c4225d086691014a806e54ad7c98766.html|REST Commands Tutorial]] * Here are example of calling the commands: [[https://help.sap.com/viewer/d0224eca81e249cb821f2cdf45a82ace/6.7.0.0/en-US/8c84b84186691014b3bcb016407a917d.html|WebService API - Reference]] ===== 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 * Source: [[https://help.sap.com/viewer/d0224eca81e249cb821f2cdf45a82ace/6.7.0.0/en-US/8c0267f486691014a66faf3be00ad744.html?q=Webservicenature|Key Features and Implementation Details]] ===== Useful Tips ===== * You can get the WADL using the url [[http://localhost:9001/trainingwebservices/rest/application.wadl|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) ===== Limitations ===== * 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