tRESTRequest Standard properties - Cloud - 8.0

ESB REST

Version
Cloud
8.0
Language
English
Product
Talend Big Data
Talend Big Data Platform
Talend Data Fabric
Talend Data Integration
Talend Data Management Platform
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Real-Time Big Data Platform
Module
Talend Studio
Content
Data Governance > Third-party systems > ESB components > ESB REST components
Data Quality and Preparation > Third-party systems > ESB components > ESB REST components
Design and Development > Third-party systems > ESB components > ESB REST components
Last publication date
2024-02-20

These properties are used to configure tRESTRequest running in the Standard Job framework.

The Standard tRESTRequest component belongs to the ESB family.

This component is relevant only when used with one of the Talend solutions with ESB, as it should be used with the Service Repository node and the Data Service creation related wizard(s).

Basic settings

API Definition / Definition

Click [...] to browse to the API definition file to initialize your component endpoint, API mappings and documentation from your API definition.

The output flow values in the API mapping are used in generated Java code, therefore they need to be camel case compliant. Output flow values are taken or computed from the API definition with these priorities:
  • operationId, which is the best practice. Even though operationId is not a mandatory field in OAS specification, it is recommended to use it at API design time.
  • summary (Name in Talend API Designer), which will be converted and truncated in 120 characters to supported format.
  • operation method and path, which will be computed with the same constraint as summary.

REST Endpoint

Fill this field with the URI location where REST-ful web service will be accessible for requests. You can either specify an explicit port number, for example, "http://localhost:8088/services/customers", or use the default port of Talend and specify the relative path only, for example, "/services/customers".

The default port is different depending on the build type or where you run the service:
  • To run the service inside Talend Studio: 8090
  • To run the service in a Talend Runtime Container: for HTTP 8040 is used for all services, and if HTTPS is enable on Talend Runtime the service is also exposed on 9001.
  • To run the service as a Microservice: 8065

You can define the endpoint using context variables.

REST API Mapping

Click the [+] button beneath the mapping table to add lines to specify HTTP request:

Output Flow: Click the [...] button to specify the name of an output flow and set the schema for that output flow in the dialog box afterwards.

The schema is not mandatory, so if you do not need to pass additional parameters to the tRESTRequest component, you can leave the schema empty. However, you will have to populate the schema if you have URI Path parameters set in the URI Pattern field or if you need to add optional request parameters such as URI Query, HTTP Header or Form parameters, to the URI specified in the REST Endpoint field.

Add a schema with the name body to get the request body of POST and PUT methods. It supports Document, String, and Byte types.

If you specify URI parameters in the output flow schema, you might need to define what type of parameter it is in the Comment field of the schema. By default, if you leave the Comment field empty, the parameter is considered as a Path parameter. Below is a list of supported Comment values:
  • empty or path corresponds to the default @PathParam,

  • query corresponds to @QueryParam,

  • form corresponds to @FormParam,

  • header corresponds to @HeaderParam.

  • matrix corresponds to @MatrixParam.

  • multipart corresponds to the CXF specific @Multipart, representing the request body. It can be used only with POST and PUT HTTP methods.

    For example, add a column number and enter query in the Comment field to get the number parameter in the request. Add a column with the same name as the header and enter header in the Comment field to fetch the HTTP header.

    You can not use API operation names with special characters, for example - or $ in the Column column as these operation names will be used as Java identifiers in generated code.

    If you have installed the R2022-02 Talend Studio Monthly update or a later one delivered by Talend, you can use any character for parameter names by adding (param-name) behind parameter type in the Comment column. This mechanism avoids failures when importing APIs from the Talend API Designer in a data service. If special characters are used in the API designer, they are replaced in the Column column to be Java compliant and real parameter name is added to the Comment column. For more information about Talend Studio Monthly update, check with your administrator.

Note: We recommend you to set the default values of your optional parameters (Header, Query, Form). To do so, fill in the Default columns of the schema.

HTTP Verb: Select a HTTP method (GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD) from the list.

URI pattern: Fill this field with REST-ful URIs that describe the resource.

Consumes: Select the format type of the consume content that the component will use from XML or JSON, XML, JSON, Form, Multipart and Any in the list when the HTTP method is POST, PUT, or PATCH.

Produces: When the HTTP method is GET, POST, PUT, PATCH, or DELETE, select the format type of the produce content that the component will use from XML or JSON, XML, JSON, HTML and Any, or select <oneway> in the list to accept one way requests.

Streaming: Select this check box to stream the response data by chunks so that the large volumes of data can be processed efficiently.

Use Service Locator Select this check box to enable the Service Locator. It maintains the availability of the service to help meet demands and service level agreements (SLAs). Specify the Service namespace and the Service name in the corresponding fields.
Use Service Activity Monitor Select this check box to enable the Service Activity Monitor. It captures events and stores this information to facilitate in-depth analysis of service activity and track-and-trace of messages throughout a business transaction. This can be used to analyze service response times, identify traffic patterns, perform root cause analysis and more.

Use Authentication (ESB runtime only)

Select this check box to enable the authentication option for the current service. This option works in runtime only. Select the authentication type from:

  • Basic HTTP: The simplest technique for enforcing access controls to web resources using standard fields in the HTTP header.
  • SAML Token: An XML-based, open-standard data format for exchanging authentication and authorization data between an identity provider and a service provider.
  • Open ID Connect: An extension for OAuth2 which allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. For more information, see Talend Identity and Access Management and Managing ESB Resources and authorizations.

Use Authorization

Select this check box to enable authorized call. This option appears when SAML Token (ESB runtime only) is selected in the Use Authentication list.

For more information about the management of user roles and rights, see Managing ESB Resources and authorizations and Talend Identity and Access Management.

Use Business Correlation

Select this check box to enable the correlation option so that chained service calls will be grouped under the same correlation ID. tRESTRequest will extract the correlation ID from the request header and store it in the component variable for further use in the flow.

If this option is not enabled on the client side, a correlation ID will be generated automatically in tRESTRequest.

Advanced settings

Log messages Select this check box to log the message exchange between the service provider and the consumer.
Wrap JSON Request Select this check box to wrap the JSON request with a root element.
Attributes to Elements Select this check box to exclude @ in the response attribute.
Convert JSON values to String in response Select this check box to convert the JSON values to string format in the response.
Service Locator Customer Properties This option appears when Use Service Locator is enabled in the Basic settings tab. Click [+] to add as many properties as needed to the table. Enter the name and the value of each property in the Property Name field and the Property Value field respectively to identify the service.
Service Activity Customer Properties This option appears when Use Service Activity Monitor is enabled in the Basic settings tab. Click [+] to add as many properties as needed to the table. Enter the name and the value of each property in the Property Name field and the Property Value field respectively to identify the service.

tStatCatcher Statistics

Select this check box to gather the Job processing metadata at a Job level as well as at each component level.

Global Variables

Global Variables

NB_LINE: the number of rows processed. This is an After variable and it returns an integer.

URI: the URI of the REST request. This is a Flow variable and it returns a string.

URI_BASE: the base URI of the REST request. This is a Flow variable and it returns a string.

URI_ABSOLUTE: the absolute URI of the REST request. This is a Flow variable and it returns a string.

HTTP_METHOD: the http method. This is a Flow variable and it returns a string.

ATTACHMENT_HEADERS: the attachment headers from the REST request. This is a Flow variable and it returns a list of attachment header values.

ATTACHMENT_FILENAMES: the attachment filenames from the REST request. This is a Flow variable and it returns all attachment filenames.

PRINCIPAL_NAME: the principal name of the REST request. This is a Flow variable and it returns a string.

CORRELATION_ID: the correlation ID by which chained service calls will be grouped. This is a Flow variable and it returns a string.

ERROR_MESSAGE: the error message generated by the component when an error occurs. This is an After variable and it returns a string. This variable functions only if the Die on error check box is cleared, if the component has this check box.

A Flow variable functions during the execution of a component while an After variable functions after the execution of the component.

To fill up a field or expression with a variable, press Ctrl+Space to access the variable list and choose the variable to use from it.

For more information about variables, see Using contexts and variables.

Usage

Usage rule

This component covers the possibility that a Talend Job can be wrapped as a service, with the ability to input a request to a service into a Job and return the Job result as a service response.

The tRESTRequest component should be used with the tRESTResponse component to provide a Job result as a response, in case of a request-response communication style.

Limitation

Using context variables for dynamic endpoint or Service Locator namespace works in Talend Studio only. It is not supported in Talend Runtime.