Abstract >> REST Services - WebMaker Documentation

WebMaker has the capability to access Rest-based services without any traditional programming. This can be achieved using a simple XML control fragment, which is processed at runtime to define the various dynamic elements such as the location URL, http request method and other parameters for the remote service. This can be achieved using the normal rules mechanism within Controllers. WebMaker can easily handle REST Services using both XML and JSON message formats. Starting with WebMaker 10.6.0002 it is now even easier to setup the Proxy that is required when calling a REST service. If you have an older version, please refer to Legacy REST Service Setup See how to use REST services with WebMaker (Note this video shows the Legacy REST Service Setup)

Setting up a REST Service Call

First open the Controller Rules for the controller that will be making the call to the REST service. If you don't yet have a controller, then create one from the Application Map. Now add an Invoke Service action to a rule, and chose the Call a REST Service option. If you have not yet set up any REST services in this project the dropdown in the Select Target Service popup will be empty, so click the Create New REST Call link. This new window will ask for the URL of the target service, and a Friendly Name to use for it within your project. Import REST service screen.

Once a URL has been provided, a guess will be made at the Friendly Name, but this can be adjusted as required. If you will be making multiple calls to this service, then ensure you enter the base URL that is common to all of them. The final URL called each time can be adjusted using the REST config discussed below. Once imported, the Invoke Service rule action will now be correctly populated. If you wish to call this service from other Rules and Controllers, you will simply need to select it from the Call Existing REST Service dropdown.

Customizing the Runtime Call Behaviour

An HttpHeader fragment can be used to dynamically set http header attributes and direct payloads to dynamically constructed URLs.This fragment should be included in the request payload to be sent for the External Call. The Insert REST Header rule action provides an easy way to setup this fragment, and should be used before the Invoke Service action. The Insert REST Header action provides a fragment like below, which can be adjusted as required. If you need to dynamically set any of these values, then you would use Assign actions after the Insert REST Header as required.

<xg:HttpHeader xmlns="http://www.hyfinity.com/xgate" xmlns:xg="http://www.hyfinity.com/xgate">
    <xg:url action="" merge_option="append" request_method="GET">/service/url</xg:url>
    <xg:params>
        <xg:param name="command">login</xg:param>
        <xg:param name="error_dest">client</xg:param>
    </xg:params>
    <xg:attributes>
        <xg:attribute name="HTTPHeaderAttrib1">attribute value</xg:attribute>
        <xg:attribute name="HTTPHeaderAttrib2">attribute Value</xg:attribute>
    </xg:attributes>
</xg:HttpHeader>

URL attributes

@action - If a non-empty string value is specified then this overrides the static action specified by default in the Invoke Service rule configuration. If an empty string value is specified then this still overrides the static action that is specified during deployment and sets the action header attribute with an empty string. If this attribute is missing then the static action value will not be overridden. If you do not want an action HTTP Header to be set at all, then set this attribute to the value NONE. @merge_option - options are replace or append. When set to replace the static url specified during web service set-up will be replaced by the URL found in the HttpHeader fragment at runtime. If the append option is specified then the static url supplied will have the dynamic url in the HttpHeader fragment appended to it. @request_method - The HTTP request method to fire. This can be one of the strings GET, POST, PUT or DELETE. If a value is not supplied or an empty string is supplied then the default will be POST.

The params will be appended to the URL in name=value pairs separated by "&" after a "?" has been inserted between the URL and the params. e.g. http://anyValidUrlString?command=login&error_dest=client The attributes will be set in the request http header before a request is made to the URL. The name attribute indicates the name of the http header attribute and the value is the value to be set for this header attribute.

Dealing with JSON Data

If your service deals with JSON formatted data, then you can use additional rule actions to convert the JSON string to XML, and vice versa. If your service returns a JSON response, then the JSON string will be available in your Controller rules within a non_xml_content element in the service response. To convert this into a structured XML format for easy binding to page fields you would use a JSON to XML Conversion action. Example rule actions showing how to process JSON response data from a REST service call.

Example rule actions showing how to process JSON response data from a REST service call.

If you are trying to post a JSON request to a service then you will need to configure the HTTPHeader as described above so that a Content-Type request header of application/json will be set. The XML data to be sent should be converted to JSON using an XML to JSON conversion action, and placed within a json_request element. The HttpHeader fragment should also be placed within the json_request before this element is sent to the Rest Service Proxy. Example rule actions showing how to post JSON data to a REST service.

Example rule actions showing how to post JSON data to a REST service.

SOAP Services Legacy REST Service Setup