How to Create a REST Web Service

Consumer Transformation

© Copyright Informatica LLC 2017. Informatica and the Informatica logo are trademarks or registered trademarks of Informatica LLC in the United States and many jurisdictions throughout the world. A current list of Informatica trademarks is available on the web at https://www.informatica.com/trademarks.html. Other company and product names may be trade names or trademarks of their respective owners.

AbstractThis article describes the REST Web Service Consumer transformation and its components: the HTTP method, the method input and method output, input and output mappings, and the base URL. Use these components to configure the transformation to communicate with a web service and the type of data that the transformation can request and receive from the web service.

Supported Versions• Informatica 10.x

Table of ContentsOverview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Transformation Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

HTTP Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Method Input and Method Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Input and Output Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Base URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Examples. Receiving Data from the Web Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Example 1. Receive Unparsed Data from the Web Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Example 2. Receive Parsed Data from the Web Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

OverviewThe REST Web Service Consumer transformation is an active transformation that communicates with a web service. The transformation sends a request to the web service to access or transform data. The web service sends back a response to the transformation that contains the requested data.

You can use the REST Web Service Consumer transformation to define the request message that you want to send and the response message that you want to receive. When you specify the response message, you can choose to receive the original message or you can choose to parse the message by specifying pre-defined fields to represent the message elements.

Transformation ElementsThe REST Web Service Consumer transformation includes the following elements:

• HTTP method

• Method input and method output

• Input and output mappings

• Base URL

When you create a REST Web Service Consumer transformation, you can define the elements and XML hierarchy manually, or you can import the elements and hierarchy from schema objects.

2

HTTP MethodWhen you run the REST Web Service Consumer transformation, the Data Integration Service uses the selected HTTP method to send an HTTP request to the web service to get, post, put, or delete data.

The following table describes each HTTP method that you can configure:

HTTP Method

Description

Get Retrieves a resource from the web service. For example, you can retrieve a table of products or retrieve information about one product.

Post Sends data to the web service. Use the Post method to create a resource. For example, you can add the details of a new store transaction.

Put Replaces a resource. If the data does not exist, the Put method posts the data. For example, you can update a customer shipping address.

Delete Deletes a resource. For example, you can delete the record of an employee that no longer works for an organization.

Method Input and Method OutputThe method input and method output definitions define the structure of the request and response messages. They are blueprints that show you the elements and element hierarchy in the request and response and represent the type of data that you want to receive from the web service.

There are two ways to define the method input and method output definitions. You can either configure each definition manually by adding the appropriate elements and child elements, or you can import a schema. You might want to use a schema if the request or response message has hundreds of elements that are difficult to add manually.

Input and Output MappingInput and output mappings depict how you map the method input or method output definition to ports in the transformation that are linked to upstream or downstream transformations.

When you create an input mapping, you map input ports to the method input definition. The input ports represent the data that you want to request from the web service. The Data Integration Service uses the method input definition to convert data from the input ports to elements in the request message.

When you create an output mapping, you map the method output definition to output ports. The method output definition defines the structure of the response message. The Data Integration Service uses the method output definition to pass the data to the output ports. The output ports represent the data that you want to use in downstream transformations. Configuring the output mapping is one way you can parse the data that you receive from the web service.

3

The following diagram shows how the input and output mappings that you configure in the REST Web Service Consumer transformation interact with the Data Integration Service and the web service:

1. Input ports from upstream transformations are linked to the REST Web Service Consumer transformations.

2. The method input definition defines the structure of the request message. The request message depends on how the input ports are mapped to the method input definition in the input mapping.

3. The Data Integration Service uses the method input definition to convert data in the input ports to elements in the request message.

4. The Data Integration Service sends the request message to the web service.

5. The Data Integration Service receives the response message according to the method output definition defined in the output mapping.

6. The Data Integration Service uses the method output definition to pass and populate the data into the output ports based on how the definition is mapped to the ports in the output mapping.

7. The output ports link the data to downstream transformations in the mapping.

4

Ports

The Data Integration Service generates the request message and passes the response message to the REST Web Service Consumer transformation based on the ports that you configure.

Input ports represent different parts of the request message. You can use input ports to build parts of the URL that you use to connect to the web service. You can add input ports that represent HTTP headers, cookie information, and elements in the request message.

Output ports represent elements in the response message that you want to send to downstream transformations or to the target in a mapping. You can add output ports that represent HTTP headers, cookie information, the response code, and elements in the response message.

The following table describes the types of ports that you can configure:

Port Description

Input Port Represents data from an upstream transformation or source that you want to pass to the web service.

Output Port Represents elements in the response message that you want to pass to a downstream transformation or to the target.

Pass-through Port Passes data through the transformation without changing the data.

Argument Port Allows you to identify a resource when the URL for the resource takes an argument. Add argument ports to the root input group.

URL Port Allows you to identify a resource through a static URL. To identify a resource, the Data Integration Service appends the value of the URL port to the base URL.

HTTP Header Port Represents HTTP headers in the request message.

Cookie Port Configures the REST Web Service Consumer transformation to use cookie authentication. The remote web server tracks the web service consumer users based on the cookies.

Output XML Port String port. Represents a response from the web service.

Response Code Port Integer port. Represents the HTTP response codes from the web service.

Base URLThe REST Web Service Consumer transformation connects to a web service through the base URL. When you run the transformation, the Data Integration Service uses the base URL to send a request and receive a response from the web service.

You can configure the base URL by specifying the URL or an HTTP connection in the advanced properties of the REST Web Service Consumer transformation. The following table describes these properties:

Property Description

Connection Identifies the HTTP connection object to connect to the web service. When you configure an HTTP connection, configure the base URL, the type of security that the web service requires, and a connection timeout period.

URL The base URL for the REST web service. The base URL in the HTTP connection overrides this value.

5

Examples. Receiving Data from the Web ServiceYou can use the REST Web Service Consumer transformation to receive unparsed or parsed data from a web service. In the following examples, we use the HTTP Get method to receive unparsed data and the HTTP Put method to receive parsed data.

Example 1. Receive Unparsed Data from the Web ServiceComplete the following steps to create the transformation:

1. In the Developer tool mapping editor, scroll down in the mapping palette to locate the REST Web Service Consumer transformation and drag it to the mapping.

The New REST Web Service Consumer Transformation wizard appears.

2. Enter a name for the transformation.

3. Next to HTTP Method, select Get.

When you use the Get method, you do not configure an input mapping.

4. Click Next.

The wizard displays a message that input is not applicable when using the Get method.

5. Click Next.

6. Select Create as empty.

7. Next to Show, select Output mapping.

6

The following image shows the options in the wizard:

8. Drag the output group from the Method output definition area on the left to the Ports area on the right.

9. Click Finish.

10. Navigate to the Ports tab of the REST Web Service Consumer transformation.

11. Highlight the output group.

12. Select New in the top right corner of the Ports tab and select Other ports. Check the box next to Output XML and click OK.

7

The Output XML port is nested under the output group as shown in the following image:

13. Navigate to the Advanced tab.

14. For the property URL, enter the base URL to connect to the web service.

15. If you use an HTTP connection, enter the connection name for the property Connection. The HTTP Connection overrides the base URL configured for the property URL.

16. For the properties Input Format and Output Format, enter the format of the request and response messages. Specify XML or JSON for each property.

The following image shows where you configure the advanced properties:

17. Run Data Viewer or run the mapping.

The following image shows an example of a response in the Output XML port:

8

Example 2. Receive Parsed Data from the Web ServiceYou can parse a message that you receive from the web service. When you parse the message, the REST Web Service Consume transformation receives data according to the structure that you specify for the response message in the method output definition.

For example, you might want to parse the following JSON response message:

{"name":"infa","message":"hello"}To parse this response message, complete the following steps when you configure the transformation:

1. In the Developer tool mapping editor, scroll down in the mapping palette to locate the REST Web Service Consumer transformation and drag it to the mapping.

The New REST Web Service Consumer Transformation wizard appears.

2. Enter a name for the transformation.

3. Next to HTTP Method, select Get.

When you use the Get method, you do not configure an input mapping.

4. Click Next.

The wizard displays a message that input is not applicable when using the Get method.

5. Click Next.

6. Select Create as empty.

7. Next to Show, select Output mapping.

8. Design the method output definition based on the response message that you expect to receive.

9

The following image shows how the method output definition might appear:

Although the transformation receives a JSON response from the web service, the Data Integration Service automatically adds a root element named xmlRoot to the JSON response. When you configure the method output definition for a JSON response, configure the same root element xmlRoot.

9. Select Output mapping.

10. Configure the output mapping by dragging ports from the Method output definition area to the Ports area.

10

The following image shows an example of the output mapping:

11. Click Finish.

12. Select the transformation and navigate to the Advanced tab.

11

13. For the property Output Format, specify JSON.

The following image shows how the transformation might appear when it is integrated in a mapping:

The following image shows the response that might appear when you run the mapping:

AuthorsMargarita PelyushenkoTechnical Writer

Pranav AchantaAssociate Product Specialist

12