cREST Standard properties - 7.3

API definition

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

Endpoint

The service endpoint URL where the REST service is provided. 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".

If you have installed the R2020-05 Studio Monthly update or a later one delivered by Talend, you can define the endpoint using context variables. For more information about Studio Monthly update, check with your administrator.

Type

Select which type you want to use to provide the REST service. Either Manual or resourceClass.

Manual: Determine the REST API mapping manually in the table if cREST is used as a service provider, or set HTTP Method and other parameters if the component is used as a service consumer.

resourceClass: Select this type to provide the resource class which you want to export as the REST service.

REST API Mapping

This table appears when the Manual service type is selected and cREST is used as a service provider.

Click [+] under the table to add as many rows as needed to specify the HTTP request:

Output Flow: Specify the name of an output flow.

HTTP Verb: Select a HTTP method from GET, POST, PUT, DELETE, OPTIONS and HEAD in the list.

URI pattern: Fill this field with the REST URI that describes 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 when HTTP Verb is POST or PUT.

Produces: Select the format type of the produce content that the component will use from XML or JSON, XML, JSON, HTML, Any when HTTP Verb is GET, POST, PUT or DELETE.

Bean class: Set the bean class when the HTTP Verb is POST or PUT and the consume content format is XML or JSON, XML or JSON.

Resource Class

This field appears when the resourceClass service type is selected. Enter the name of the resource class which you want to export as the REST service.

Operation

This field appears when the resourceClass service type is selected and cREST is used as the service consumer. Enter the name of the operation.

Relative Path

This field appears when the Manual service type is selected and cREST is used as the service consumer. Enter the relative path of the REST server to be invoked.

HTTP Method

Content Type

This option appears when the Manual service type is selected and cREST is used as the service consumer.

Select XML, JSON, or FORM according to the media type of the content to be uploaded to the server end. This list appears only when you select the POST or PUT in the HTTP Method list.

Accept Type

This field appears when the Manual service type is selected and cREST is used as the service consumer.

Select the media type the client end is prepared to accept for the response from the server end. Available options are XML, JSON, and ANY. When ANY is selected, the response message can be of any type and will be transformed into a string. This list does not appear when you select the DELETE method.

Response Class

This field appears when the Manual service type is selected and the cREST is used as the service consumer. Enter the name of the response class.

Skip incoming data unmarshalling

Use Service Locator

Select this check box to enable the Service Locator. Specify the service namespace and the service name in the corresponding fields.

Enable the Service Activity Monitoring

Select this check box to enable the Service Activity Monitor.

Note that this option works in Runtime only. When running the Route in the Studio, it is recommended to clear this check box. Otherwise warnings will be thrown in the execution console.

Use Authentication

Select this check box to enable the authentication option. Select the authentication type from:

• HTTP Basic: The simplest technique for enforcing access controls to web resources using standard fields in the HTTP header.
• SAML Token (ESB runtime only): 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.

When the cREST component is used as consumer, enter a username and a password in the corresponding fields as required. To enter the password, click the [...] button next to the password field, and then in the pop-up dialog box enter the password between double quotes and click OK to save the settings.

Use Authorization

This option is only available if you subscribed to Talend Enterprise ESB solutions. It appears when SAML Token (ESB runtime only) is selected in the Use Authentication list.

When the cREST component is used as the service provider, select this check box to enable authorization.

When the cREST component is used as the service consumer, select this check box to invoke authorized call and specify the client's role in the Role field.

Use Business Correlation

Select this check box to create a correlation ID in this component.

You can specify a correlation ID in the Correlation Value field.

Log messages

Select this check box to log the message exchanges in the Route.

Expose Swagger specification

This option appears when cREST is used as a service provider, and is available only when the Manual service type is selected. Select this check box to expose the Swagger specification and include the Swagger UI into the REST service, which provides an online API Documentation in human-readable form and some basic test features.

If the Route is running in the Studio, the Swagger specification will be available at http://127.0.0.1:8090/ENDPOINT/swagger.json and http://127.0.0.1:8090/ENDPOINT/swagger.yaml. The Swagger UI is not available.

If the Route is running in Talend Runtime, the Swagger specification will be available at http://127.0.0.1:8040/services/ENDPOINT/swagger.json and http://127.0.0.1:8040/services/ENDPOINT/swagger.yaml. The Swagger UI will be available at http://127.0.0.1:8040/services/ENDPOINT/api-docs?url=/services/ENDPOINT/swagger.json.

If the Route is running as a ESB Microservice, the Swagger specification will be available at http://127.0.0.1:8065/services/ENDPOINT/swagger.json and http://127.0.0.1:8065/services/ENDPOINT/swagger.yaml. The Swagger UI will be available at http://127.0.0.1:8065/services/ENDPOINT/api-docs?url=/services/ENDPOINT/swagger.json.

For more information about how to build a Route to a ESB Microservice and how to run the Microservice, see Talend Studio User Guide.

Include Documentation into Swagger Spec

This option appears when cREST is used as a service provider and the Expose Swagger specification check box is selected. Select this option to add content in the Comment field of the Documentation tab of this component into the Swagger specification and the Swagger UI page.

For more information about the Documentation tab, see Talend Studio User Guide.

Usage rule

cREST can be a start component in a Route as the service provider, or middle or end component as the service consumer.

Limitation

Due to license incompatibility, one or more JARs required to use this component are not provided. You can install the missing JARs for this particular component by clicking the Install button on the Component tab view. You can also find out and add all missing JARs easily on the Modules tab in the Integration perspective of your studio. For details, see Installing external modules. You can find more details about how to install external modules in Talend Help Center (https://help.talend.com).