Building a simple REST service - 6.1

Talend ESB Hands-on Guide

EnrichVersion
6.1
EnrichProdName
Talend Data Fabric
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Open Studio for ESB
Talend Real-Time Big Data Platform
task
Administration and Monitoring
Deployment
Design and Development
Installation and Upgrade
EnrichPlatform
Talend Administration Center
Talend ESB
Talend Runtime
Talend Studio

This section provides you a step by step instruction to build the REST service provider. Unlike SOAP services which are built via a [Service] wizard, REST services are built through the a [Job Design] wizard of the Talend Studio.

In this section, you will create:

  1. A simple REST service provider querying the data of your employees. See Creating a service provider.

  2. A second REST mapping to query only one specific employee via their id. See Adding a new mapping to the service.

Creating a service provider

In this section, you will create a REST service giving access to a list of employees and their data. For more information, see Web Services Support.

Creating the Job

  1. To create the service, right-click Job Designs in the left hand menu and select Create Job.

  2. Enter the name (EmployeeService), the purpose (demo) and a description of the service, and click Finish to return to the main screen.

    Now, the main screen has a Job EmployeeService 0.1 tab displayed.

  3. In this new Job Design, you will build the REST service, so search for tRESTRequest and tRESTResponse components in the palette, and drag and drop them onto the grid.

    Similarly, drag and drop tFlowToIterate, tFixedFlowInput, and tXMLMap components as shown below.

Configuring the REST request

  1. Double-click the tFixedFlowInput component to display its corresponding Component view at the bottom of the window. Click the [...] button next to the Edit schema option.

    In the [Schema of tFixedFlowInput] wizard that pops up, click three times the [+] button at the bottom of the wizard to add three columns and configure them as above.

  2. In the Mode area, select the Use Inline Content (delimited file) option and paste the following info in the Content field:

    1;Lyndon;Monroe
    2;John;Johnson
    3;Calvin;McKinley
    4;Andrew;Truman
    5;Richard;Taft
    6;Andrew;Adams
    7;Herbert;Buchanan
    8;Bill;Carter
    9;Ulysses;Jackson
    10;Warren;McKinley

  3. Double-click tRESTRequest to display its corresponding Component view and set its properties.

  4. In the REST Endpoint field, you can type in the URI of the endpoint from which the service will be available. The URI is generally made of a Host name or IP address and a port number, separated by a colon. Here, put the relative path "/services". This way, the URI will always look as follows: http://<IP_address>:<port_number>/services.

  5. Click once the [+] button at the bottom of the REST API Mapping table to add a new mapping.

  6. In the HTTP Verb field, leave the GET operation.

  7. In the URI Pattern field, type in the XPath to the root of the XML tree: "/employees".

  8. Click in the Output Flow field to display the [...] button and click it.

    The [Give the name for the schema] wizard pops up.

  9. In the Schema Name field, name it getEmployees and click OK.

    A new wizard pops up in which you can define the columns of the schema you are about to create.

  10. As you do not want to define any schema for this REST API Mapping for the time being, simply click OK.

    The new getEmployees mapping displays in the REST API Mapping table.

Connecting the components together

  1. Right-click tRESTRequest, select Row > getEmployees in the menu and click the tFlowToIterate component.

  2. Right-click tFlowToIterate, select Row > Iterate in the menu and click the tFixedFlowInput component.

  3. Right-click tFixedFlowInput, hold and drag to tXMLMap.

  4. Right-click tXMLMap, hold and drag to tRESTResponse and name the output link all when asked by the [tXMLMap Output] pop-up.

Configuring the tXMLMap

  1. Double-click it to open its editor.

  2. In the editor, the input flow from the database table displays to the left, in the input area of the editor. And in the output area to the right of the editor, configure the output XML flow that will be sent to the tRESTResponse component.

  3. In the all output table, right-click the root element and select Rename in the menu to rename it employees.

    Now, define the XML tree of the employees root element.

  4. Right-click employees and select Create Sub-Element in the menu to create a sub-element called employee that will hold each employee's information.

  5. Right-click this new employee sub-element and select As loop element in the menu.

    This way, a loop will be executed at each new employee encountered, to retrieve their individual information.

  6. Click the Wrench button at the top of the table to display the output options and select true in the All in one list.

    When set to true, the All in one option enables to create one single XML document from all the input rows of the tXMLMap component. This allows to send only one complete response when the Web Service is called.

  7. Map the input with the output flow, select the id column from the row1 table and drop it onto the employee sub-element of the all table, a [Selection] wizard pops up.

  8. In the wizard, select Create as attribute of target node and click OK to validate.

    A mapping has been created between the id column of the employees database table and the id attribute of the employee XML tree.

  9. Select the firstname and lastname columns of the row1 table and drop them onto the employee sub-element of the all output table.

  10. In the [Selection] wizard, select Create as sub-element of target node and click OK to validate.

    The mapping between the input and output flow is complete.

  11. Click Apply and OK to close the editor and validate the configuration.

Executing the Job

  1. Press F6 to run the Job. The Job is automatically saved before being executed. The Run view displays at the bottom of the Studio and the console follows the execution.

    The REST Service has been published to the following endpoint: http://127.0.0.1:8090/services, and the provider continuously listens for request, so if you want to stop it, you will have to click the Kill button of the Run view.

  2. To check the service, simply go to the endpoint address on which it has been published: http://127.0.0.1:8090/services/employees.

Adding a new mapping to the service

In the previous section (Creating a service provider), you saw how to create a REST service retrieving all the employees' information. Now, to be able to browse each employee's information individually, you will have to add a new REST mapping.

Modifying the REST request

  1. In the EmployeeService Job, double-click the tRESTRequest component to display its corresponding Component view and change its properties.

  2. Click once on the [+] button at the bottom of the REST API Mapping table to add a new mapping.

  3. In the HTTP Verb field, leave the GET operation.

  4. Leave the URI Pattern field as is for the moment.

  5. Click in the Output Flow field to display the [...] button and click it.

    The [Give the name for the schema] dialog box pops up.

  6. In the Schema Name field, name it getEmployee and click OK.

  7. In the schema wizard, click the [+] button once to add a new line to the table.

    Rename it id and change its Type to Integer. Click OK to validate.

    The new getEmployee mapping displays in the REST API Mapping table.

  8. In the URI Pattern field, type in the XPath to the root of the XML tree followed by the id variable to each employee: "/employees/{id}".

  9. Duplicate the tFixedFlowInput and tRESTResponse component, simply by coping and pasting them.

  10. Click on the workspace, and start typing the name of the tXMLMap component, where you want to add it, in the text field that appears automatically, and double-click its name to add it on the workspace.

Connecting the components together

  1. Right-click tRESTRequest, select Row > getEmployee in the menu and click the second tXMLMap component.

  2. Right-click the second tFixedFlowInput component, hold and drag to the second tXMLMap.

  3. Right-click the second tXMLMap component, hold and drag to the second tRESTResponse component and name the output link single when asked by the [tXMLMap Output] pop-up.

Configuring the second tXMLMap

  1. To configure the second tXMLMap, double-click it to open its editor.

  2. Select the id column of the getEmployee input table and drag it to the id column of the row2 table.

    A purple arrow is created between the columns of the tables to represent the join.

  3. Define the XML schema that will be sent to the tRESTResponse component. To do so, right-click the root element node in the single table and select Rename in the menu to rename it employee.

  4. Map the input with the output flow. To do so, select the id column from the row2 table and drop it onto the employee element of the single table, a [Selection] wizard pops up.

  5. In the wizard, select Create as attribute of target node and click OK to validate.

  6. Now, select the firstname and lastname columns of the row2 table and drop them onto the employee element of the single output table.

  7. In the [Selection] wizard, select Create as sub-element of target node and click OK to validate.

    The mapping between the input and output flow is complete.

  8. Click Apply and OK to close the editor and validate the configuration.

Executing the Job

  1. Press F6 to run the Job. The Job is automatically saved before being executed. The Run view displays at the bottom of the Studio and the console follows the execution.

    The REST Service has been published to the following endpoint: http://127.0.0.1:8090/services, and the provider continuously listens for request, so if you want to stop it, you will have to click the Kill button of the Run view.

  2. To check the service, simply go to the endpoint address on which it has been published: http://127.0.0.1:8090/services/employees.

    You can see that it looks just like in the previous scenario.

  3. Now, if you add the id of one of the employees at the end of the URL: http://127.0.0.1:8090/services/employees/1

    Only the information about this employee displays.