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 HCL Commerce best practices.

Procedure

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
                    endRequest(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 HCL Commerce REST API:
- REST API