Skip to main content
Skip table of contents

RESTConsumer

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 and DELETE 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.

The elements dialog in representation will be populated from the schemas that are specified in this panel.

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:

CODE
http(s)://<hostname:<port>/<static path segment>.

If the base URI changes across invocations, it can be specified in the input message using the ResourceURL element.

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.

Additional Configuration


Figure 18: Additional Configuration

Please refer the respective sections in Common Configurations page.

Error Handling


Figure 19: Error Handling properties

Please refer Error Handling section in Common Configurations page.

Encrypt/Decrypt Configuration


Figure 20: Encrypt/Decrypt Configuration properties

Please refer Encrypt Decrypt Configuration section in Common Configurations page.

Port Generation


Figure 21: 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 22: 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 23: 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 child element of the root element. The status of the response is present as 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 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 24: 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:

These scenarios involve the RESTStub microservice as well, which works in conjunction with RESTStub. Refer to the RESTStub documentation to configure and run the event processes.

Useful Tips

  • To invoke URL of a RESTful service, use the functionality Load WADL from URL as demonstrated in 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.

To understand the service better, refer the REST Attachments example which demonstrates RESTConsumer service features.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.