This component is used to invoke RESTful services that are deployed on Web Servers. Existing WADLs can be directly loaded into the component. It is also possible to invoke GET, PUT, POST, DELETE and PATCH commands on normal HTTP Endpoints.
The component can be configured by manually defining the resources and methods that are supported by the service in the CPS of the component.
The WADL generated for the component will differ from the WADL provided in following aspects:
- If the provided WADL contains multiple 'resources' elements, only the first resources element will be loaded and used.
- The component generates Request and Response Port for each method present in the configured web service.
Configuration
The component can be configured using the Configuration Property Sheet (CPS) as shown in the following sections.
WADL Definition
Figure 1: Configuration Property Sheet
This page is used to define the RESTFul service using a user interface for WADL. User can create a WADL by manually defining different aspects of the service.
WADL Definition Views
Details of the selected WADL are shown in 2 different views—Configuration and WADL. However, web service can be configured using Configuration view only.
Configuration View
The RESTful service can be configured by selecting the nodes in the tree on the left side. When a node is selected in the tree the panel corresponding to its configuration is shown in the right side pane. The details of different panels corresponding to the nodes are as explained in the following sections.
Schemas
Figure 2: Schemas Configuration
The XML schemas which are required for the request and response messages have to be specified in this panel. A schema can be added by clicking the 
button in the table shown in the figure above.
There are 3 ways to add schema to schema repository; Load from File, Load from Port Schemas and Load from Schema Repository. When Load from File is choosed, selected content in the schema file is shown in the area given. When Load from Port Schemas is choosed, schema is directly added to the schema repository. When Load from Schema Repository is choosed, schema can be fetched from schema repository. In this case, the required schemas have to be added to the schema repository using Studio.
Resources
The resources node will act as parent of all the resources that are added as part of this service. It provides the base path for all these resources.
Figure 3: Base Path configuration
The base URI of the service that is being consumed has to be specified here. In general, it will be of the format:
Resource Configuration
A resource logically represents a entity whose operations have to be exposed using the RESTful service. It may optionally be used to specify just a path segment for a child URL with no methods defined on the resource itself.
Figure 4: Adding child resources and methods
A resource can be added to a resources/resource element by selecting the option Add Resource/Add Child Resource respectively as shown in the figure above.
Figure 5: Resource configuration
The configuration of a resource contains fields as explained below.
ID
The identifier for the resource can be specified using this element. This identifier is used in the generation of port names and schemas corresponding to the methods that are defined on this resource or any of its child resources.
The ID has to be unique among its siblings. The complete ID of a resource will be computed using information of parent IDs as below.
Example:
If the resource with ID "parent" is added to Resources element (using Add Resource option) and a child is added to the resource (using "Add Child Resource" option) with ID "child", the complete ID of the resource will be parent__child.
Path
The path of the resource, relative to its parent resource/resources element has to be specified against this field.
The path of a resource has to be unique among the siblings of a resource. The path of a resource will be computed including information of parent paths as below.
Example:
If the resource with path "parent" is added to Resources element (using Add Resource option) and a child is added to the resource (using "Add Child Resource" option) with path "child", the actual path of the resource will be <Resources Base Path>/parent/child.
Templates are allowed in the path element. A template will have the form {<template name>}. When a template element is used a parameter with same name and style as Template have to be defined. The request message on the port corresponding to this resource must have the value of the template parameter as the value that is being requested.
Example:
If a request has to be sent to URL <Parent Path>/<template> where the value of template name is dynamic then
- The resource(id resourceID) path must be specified as {<templateName>}.
- A parameter templateName must be specified with style "Template" for this resource.
- The actual value of the template must be passed in the request as shown below.
.. <resourceID>
<templateName>178</templateName>
</resourceID>..
Please refer to generation of schemas for more information on parameter.
QueryType
The property defines the media type for the query component of the resource URI. The value defaults to 'application/x-ww-form-urlencoded' if not specified which results in query strings being formatted as specified in section 17.13 of HTML 4.01.
Method Configuration
Methods that resource supports can be added by using the context menu of a resource.
Figure 6: Method Configuration
The request configuration of a method can also be configured in this panel. The various attributes of a method are explained below.
Name
The attribute hold the name of the method that the resource supports. The attribute is non editable. The name will be used in the generation of ports and schemas for the component.
Two methods on a resource can have the same method name. In such case ID has to be specified for the method to differentiate between the methods.
ID
The method ID acts as a differentiator between methods of a same resource with same name. This is required only if the resource defines more than one method with the same name.
Request configuration
The request for a message can be configured in the panel corresponding to the method as shown in Figure 6. As part of request one can define multiple representations. Different representations can have different media types and elements defined. The media Type requested will be sent as part of the request message. It's the responsibility of the event process developer to return the appropriate content type based on the request.
Configuring representations is explained in detail in Response Configuration section below.
Similarly the request parameters can be configured for a particular method by using the parameters tab. Configuring parameters is explained in detail in Representation Configuration section below (after Response Configuration section).
Response Configuration
A method can have multiple responses. Different responses cater to different sets of status codes. A response element can be added by using the context menu on a method.
Figure 7: Adding Response
The response can be configured using the panel as shown below.
Figure 8: Response configuration
Status
Figure 9: Configuring status
The status of response can be space separate list of the standard HTTP status codes or any custom codes defined in the application. The status codes can be selected among standard HTTP status codes by clicking on ellipsis against this property.
Representations
Similar to a request, each response (corresponding to a set of statuses) can have multiple representations. The representations provide different views of same response as defined by the media type.
Representation configuration
Multiple representations can be defined for both request and response of a method.
Figure 10: Representation Configuration
Element
The element can be used to specify the xml schema of an element corresponding to the representation. The schema corresponding to the element has to be added to the schema repository using studio and an include has to be added using the Schemas panel as explained in Schemas section above.
The element can then be selected by clicking on the ellipsis and selecting element.
Figure 11: Configuring elements
MediaType
The media type of a representation defines the type of the content that is present in the representation. The media type can be configured by selecting the appropriate one from the drop down or manually specifying in the combo.
Figure 12: Media Type configuration
Profile
The attribute is similar to the HTML profile attribute, gives the location of one or more meta data profiles, separated by white space. The meta-data profiles define the meaning of the rel and rev attributes of descendent link elements
Parameter configuration
Figure 13: Parameter Configuration
Refer the respective section as above in RESTStub page.
Error Notifications
Figure 14: Error Notifications
The validation for a particular panel is done when the user tries to navigate away from the tree node corresponding to the panel. Validation errors corresponding to the particular panel are shown using the error notifying dialog as above.
WADL
This is a read only view of the WADL that is generated from the configuration done using configuration view.
Figure 15: WADL view
Transport Security
SSL Configuration
Figure 16: SSL Configuration properties
To consume a RESTful service using SSL the component must be configured to use SSL Configuration. Please refer SSL Configuration section in JMSIn5.0 page for configuration details.
HTTP Authentication
Figure 17: HTTP Authentication properties
Use HTTP Authentication
To connect to RESTful service where the basic authentication is present, the HTTP authentication has to be configured in the component.
Type
The type of HTTP Authentication can be selected for the drop down. At present only BASIC authentication is supported.
Username
Username to be used to connect to the Web Service has to be specified here.
Password
Password for the username specified can be specified using this field.
Token Authentication Configuration
Figure 18: Token Authentication Configuration properties
Use Token Authentication
Enables Token Authentication for all routes in RestConsumer
- Authentication Base Path: The base path which hosts the authentication resource
- Authentication Resource ID: The route configured in the Resource Configuration panel which would be responsible for token authentication and token issue
- Token Expired Response Status Code: The response code which would be returned for routes, if the token is expired in order to automatically manage re-fetching of tokens
- Token Key Name: The key name which would contain the token in response payload upon successful token issue from token issue route
Additional Configuration
Figure 19: Additional Configuration
Please refer the respective sections in Common Configurations page.
Error Handling
Figure 20: Error Handling properties
Please refer Error Handling section in Common Configurations page.
Encrypt/Decrypt Configuration
Figure 21: Encrypt/Decrypt Configuration properties
Please refer Encrypt Decrypt Configuration section in Common Configurations page.
Port Generation
Figure 22: Sample Configuration
A request port and response port are generated for each method configured in the component with suffixes __Request and __Response respectively. The prefix of the port name will be the complete ID of the resource computed (as described in the Resource section above) followed by the method name.
If a resource has multiple methods with same name (two GET methods) then the method ID has to be specified for at least one of those methods. The method ID will be appended to the port name prefix to differentiate between these methods. For the sample configuration defined in Figure 21, the ports will be generated as below.
Figure 23: Port Generation
Schema Generation
The schemas are automatically generated for the ports based on the configuration
Request Schema
The schema of the input port corresponding to a method depends on its configuration and its parent resources.
The optional element ResourceURL can be used to dynamically invoke a RESTful service based on the input message. The value specified will be given preference over the base URL specified in the CPS.
The resource parameters configured are added as child element of the element ResourceParameters. The hierarchy of the resources is maintained as it is in the resource chain corresponding to the method. The parameters of a resource are added as its child elements.
The methods request parameters are added as child elements to the element RequestParameters. The various representations of the request are added as child elements of element Representations. The element specified is present as child element of Element and the representation's parameters are added as child elements of element representationParameters.
The optional Parameters element can be used to send any parameters that are not present as part of the configuration.
For the sample configuration shown in Figure 21, the schema generated for port parent__POST_Request is as below.
Figure 24: Schema of port parent__POST_Request
Response Schema
The schema of the output port corresponding to a method depends on its configuration. Schema is populated on the response port of a method only if it has a response as its child element.
For each response configured a Response element is added as a child element of the root element. The status of the response is present as an attribute of this element. The response parameters corresponding to a particular Response are added as child elements to the element ResponseParameters.
The various representations of the response are added as child elements of element Representations. The element specified is present as a child element of Element and the representation's parameters are added as child elements of element representationParameters.
For the sample configuration shown in Figure 21, the schema generated for port parent_child1_GET_Response is as below.
Figure 25: Schema of port parent_child1_GET_Response
Functional Demonstration
Refer to the REST Services section for a detailed demonstration of functionalities of each of the below:
Configuring Token Authentication in RESTConsumer
Configure the base path for REST requests with the adequate URL.
- Configure the resource request for routes that would require Token Authentication on REST Request entry.
- Configure the Response Configuration to add the response codes along with the response code which would be returned at the time of token expiry (In this case, 401 denotes an expired token for routes expecting token)
- Configure the token authentication resource which would handle the token issue and token reissue in case of expiry.
- Configure the Request Configuration for the REST request.
- Go to Method Configuration > Request Configuration > Parameters and add the parameters such as username and password.
Navigate to the Token Authentication Configuration tab and provide the values. Select the appropriate Authentication Resource ID which would handle token issue and token expiry.
- Configure the event process with a RESTConsumer connected to a Feeder and a Display.
- In the example server hosted for Token issue and expiry, the server stores username and password which can be done through a REST Request.
Ensure that the Username and password are permitted for the REST request and enter the sample input XML in the Feeder window as below.
Sample Input
- The output comes as shown in the figure below upon successful request.
- In case of token expiry, the request for reissue is automatically handled by the RestConsumer with no intervention required.
Useful Tips
- To invoke URL of a RESTful service, use the functionality Load WADL from URL as demonstrated in the Functional Demonstration section.
- If RESTConsumer is used to invoke RESTStub which is running on a peer server with both jms ssl enabled and jetty ssl enabled, the keystore used to connect to jetty ssl is to be imported into jms ssl keystore %FIORANO_HOME%\esb\server\profiles\certs\jssecacerts.
- When the content type of request is application/octet-stream the content is sent as bytes content in the message, this will be present as bytes property. This can be retrieved as Base 64 encoded string in mapper using the funclet Byte-Content in JMS Message funclets.
- For invocation of RESTful services whose base URL is dynamic, use the elements ResourceURL and Parameters from the request schema.
- For dynamic invocation, if empty values are allowed in the query parameters, they need to be concatenated to the ResourceURL element.