Feature Pack 7 or later

Best practices for mapping REST API methods to controller commands

Follow the sample code and coding tips to ensure that your new or custom REST controller command services conform to WebSphere Commerce best practices.


  • When creating and naming controller command services:
    • Create a resource handler for the controller commands that use the same noun by extending the AbstractClassicResourceHandler class. The recommended naming convention for the resource handler is ControllerCommandNounCmdHandler. For example, OrderItemCmdHandler.java.
    • The URL naming convention for the controller command can follow one of the following methods, depending on your requirements:
      1. Following Create, Read, Update, and Delete (CRUD) operations:
        • For Create: POST, store/{storeId}/{ControllerCommandNoun}. For example, store/11051/orderitem.
        • For Update: PUT, either store/{storeId}/{ControllerCommandNoun}. For example, store/11051/orderitem, or

          store/{storeId}/{ControllerCommandNoun}/{byCriteria}/{criteriaIdentifier}. For example, store/11051/orderitem/byOrderItemId/45002.

        • For Delete: DELETE, store/{storeId}/{ControllerCommandNoun}/{byCriteria}/criteriaIdentifier. For example, store/11051/orderitem/byOrderItemId/45002.
      2. Following generic naming conventions that are based on actions:
        • POST, store/{storeId}/{ControllerCommandNoun}/{action}.

          For example, store/11051/order/copy, store/11051/order/calculate, or store/11051/orderitem/move.

    • The command parameters (name-value pairs) can be sent as the URL path parameters, as the URL query parameters or in the request content, or both. They must be set to the request properties before the command is called.
    • The response properties (TypedProperty class) are serialized and returned after the command is run.
  • The following sample code invokes a controller command in the command resource handler:
    String cmdRefKey = OrderItemDeleteCmd.NAME;
    TypedProperty requestProperties = null;
    response = executeControllerCommandWithContext(storeId, cmdRefKey, requestProperties, responseFormat);
    // the response object here is already formatted and can be returned via Rest
         * This methods sets up the BCS by calling startRequest(),
         * executes the controller command, and then ends the BCS by calling
         * endRequest(BusinessContextService).
         * @param storeId the store ID
         * @param cmdRefKey the command interface name
         * @param requestProperties the request properties
         * @param responseFormat the response format
         * @return the response
        protected Response executeControllerCommandWithContext(String, String, TypedProperty, String);
  • The following sample code manipulates the command parameters before the single controller command is run. Add the following code before calling executeControllerCommandWithContext(String, String, TypedProperty, String):
    // if custom logic is needed to set command parameter prior to command
    // execution, here are some sample code to do so
    // for OrderCopyCmd, URL is a mandatory parameter
    TypedProperty requestProperties = initializeRequestPropertiesFromRequestMap(responseFormat);
    requestProperties.put("URL", "URL");
         * This method creates a request properties from the request map.
         * @param responseFormat the response format
         * @throws Exception the exception occurs
        protected TypedProperty initializeRequestPropertiesFromRequestMap(String) throws Exception;
  • The following sample code runs multiple controller commands in a custom resource handler:
    // setting up the BCS
                    BusinessContextService bcs = startRequest();
                    try {
                        cmdRefKey = OrderCopyCmd.NAME;
                        requestPropertiesForCopy = initializeRequestPropertiesFromRequestMap(responseFormat);
                        requestPropertiesForCopy.put("URL", "URL");
                        // invoke the first controller command
                        TypedProperty responsePropertiesOfCopy = executeControllerCommand(storeId, cmdRefKey, requestPropertiesForCopy, responseFormat);
                        responseProperties = addToResponse(responseProperties, responsePropertiesOfCopy, "copyResponse");
                        cmdRefKey = OrderCalculateCmd.NAME;
                        requestPropertiesForCal = new TypedProperty();
                        String[] orderIdList = (String[])responsePropertiesOfCopy.get("orderId");
                        for (int i=0; i<orderIdList.length; i++) {
                            requestPropertiesForCal.put("orderId_"+(i+1), orderIdList[i]);
                        // invoke the next controller command
                        TypedProperty responsePropertiesOfCal = executeControllerCommand(storeId, cmdRefKey, requestPropertiesForCal, responseFormat);
                        responseProperties = addToResponse(responseProperties, responsePropertiesOfCal, "calculateResponse");
                        response = generateResponseFromHttpStatusCodeAndRespData(responseFormat, responseProperties.getMap(), HttpStatus.OK);
                        // clean up the BCS
         * This method associates the BCS with the activity data and the activity token by
         * calling BusinessContextService startRequest(ActivityToken, ActivityData)
         * to perform any necessary set up for request execution.
         * @throws Exception the exception occurs
        protected BusinessContextService startRequest() throws Exception;
         * This method creates a command context, looks up the command implementation from the command
         * registry, associates the command context created and the request properties to the command.  
         * It also performs command level and resource level access control check before invoking the
         * command.
         * @param storeId the store ID
         * @param cmdRefKey the command interface name
         * @param requestProperties the request properties
         * @param responseFormat the response format
         * @return the response properties from the command
         * @throws Exception the exception occurs
        protected TypedProperty executeControllerCommand(String, String, TypedProperty, String) throws Exception;
         * This method generates REST response for a given response map.
         * Use this method in your resource handler class when you want to pass name value pairs to
         * the entity provider.
         * @param responseFormat the response format shortcut. Response format is used to resolve the
         * media type for the REST response. If response format is not provided, then Accept
         * header is used to resolve the media type for the REST response. Refer to {@link RestServicesUtils#getResponseMediaType(String, Request)}
         * for more details on the response media type resolution.
         * @param responseData the response map to pass to the entity provider.
         * @param statusCode the HTTP status code to set in the REST response.
         * @return the REST response.
        public Response generateResponseFromHttpStatusCodeAndRespData(String, Map<String, Object>, HttpStatus);  
         * This method calls BusinessContextService endRequest(ActivityToken)
         * to perform any necessary cleanup after request execution.
         * @param bcs the business context
         * @throws Exception the exception occurs
        protected void endRequest(BusinessContextService) throws Exception;
  • Each REST resource contains information such as URLs, descriptions, and sample input and output data in the WebSphere Commerce REST API: