Getting Started with HTTP REST

Overview

The HTTP REST metadata is shipped with a wizard to help users test and reverse HTTP REST Web Services.

This wizard allows defining the input and output parameters, the URL to request, and the method to use and perform a test request with test values to see the response of the Web Services. It also offers the possibility to determine what should be reverse-engineered in the metadata.

Create Metadata

To create metadata:

  1. Right-click the project folder, then click New > Metadata.

  2. In the Create Metadata dialog, select HTTP REST and click Next.

  3. Name the data model and click Next.

  4. Select the installed HTTP REST module and click Finish.
    A wizard displays. It allows you to define the HTTP security and proxy settings as well as the reverse-engineer URL or files.

  5. In Security Definition, set the following properties:

    • HTTP Security: Select an HTTP Security configuration previously created in an HTTP Security metadata. APIs may be accessed using one of the following methods:

      • None (default): No credentials are required to access the API.

      • User credentials: User credentials are required to access the API. The credentials specified in Semarchy xDI Designer are used by default.

      • OAuth2 security: OAuth2 is required to access the API.

    • In HTTP Proxy: Select an HTTP Proxy configuration, previously configured in a Proxy Security metadata.

      The above fields display and use Proxy Security and HTTP Security metadata available in the workspace.

  6. Click Next.

  7. In the Reverse step, set the following fields:

    • Reverse URL or File: Specify a URL or use the browse button to specify the path to a file that you want to reverse-engineer.

    • HTTP Keystore: Specify the keystore information defined in the Certificate and Keys metadata.

    • HTTP Truststore: Specify the truststore information defined in the Certificate and Keys metadata.

  8. Click Next.

  9. In the Selective Reverse step, select the node that you want to reverse-engineer.

  10. Click Finish.

The HTTP REST metadata node is created.

Test the API Response and Reverse-Engineer the Data

You can also test the API response and reverse-engineer the data after ensuring that the API response corresponds to what is expected.

To test the API response:

  1. Right-click an operation node. For example, the GET node.

  2. In the contextual menu, click Actions > Reverse REST.
    The RESTFull Reverse window appears.

  3. Define the request parameters, headers, body, and authentication.

  4. Once the API request is defined, click getting started run test.
    The API is called with the defined parameters, and the response appears in the Response section.

  5. Click Next after ensuring that the response corresponds to what is expected.
    The Selective Reverse step appears.

  6. Select the nodes that you want to reverse-engineer and click Finish.

Request Parameters

In the Parameters section, you can define new parameters by clicking the getting started add button.

Value

The value is a test value that is used when performing a test invocation to retrieve the response of the API. It is not stored in the Metadata at the end.

Type

The following table describes the types of parameters:

Table 1. Parameter Types
Type Description

HEADER

Parameter that is added as HTTP header when invoking the API.

The HTTP header thus defined is reversed in the input metadata of the API and is specified dynamically in the mappings that invoke the API.

QUERY

Parameter that is added at the end of the request URL.

PATH

Parameter that replaces a user-defined mask in the request URL.

When you select this option, add the mask to be replaced in the request URL.

FORM

When you select this option, the Allow Empty Value checkbox is automatically selected as its values are derived from the fields in the Input section.

In the Input section:

  • The Media Type field is automatically set to FORM and cannot be modified.

  • Set the Content-Type Header field to application/x-www-form-urlencoded.

COOKIE

When you select this option, the specified cookies are sent each time a request is sent. The cookies are not stored.

Request Body

The request body represents the input body of the HTTP request.

If the API expects an input body, select the associated type and fill in the body expression:

An option to link the selected Media Type with the Content-Type Header is available:

  • When the link is disabled, users can select Media Type and manually select the Content-Type Header.

  • When the link is enabled, after each Media Type selection, the Content-Type Header is automatically updated according to the selected Media Type. However, users can manually change the content type.

Request Authentication

The Authentication section allows you to define the mechanism that should be used to authenticate when invoking the API.

Table 2. Authentication
Field Description

Authentication Type

Type of authentication to use. Possible values are:

  • None

  • Basic

  • OAuth

  • OAuth2

  • NTLM

Select None or Basic if the API does not require any authentication.

Security Reference

HTTP security metadata node containing the authentication information.

Security Proxy Reference

Proxy security metadata node to use if the request is redirected through a proxy.

This is not the proxy setting for the API invocation, but the authentication that should be used if the request is redirected by a proxy.

Keystore Reference

Certificate and Keys metadata node to use as keystore reference.

Truststore Reference

Certificate and Keys metadata node to use as truststore reference.

Create Mappings

Once the HTTP REST metadata is ready, you can use it in mappings.

In the following example of mapping, the fields from the source table are mapped to the JSON nodes in the Request Body node of the POST function of the HTTP REST API. These fields are used as request parameters. The response received is stored in the Responses node. The response nodes are mapped to the fields in the target table.

getting started mapping

Error Management

Summary

The HTTP REST component provides parameters to manage both the functional and technical errors that can be encountered when making API calls.

The parameters described in this section are used to define the retry behaviors, the number of accepted errors, and more.

The parameters are available directly within the mapping, in the INTEGRATION Rdbms to HTTP Template.

Functional Errors Parameters

Functional Error Acceptance Number

A functional error happens when the target API is reachable but returns an HTTP code different than 200. (E.g. 404, 500, …​).

This parameter defines the number of functional errors tolerated before considering the data flow as a failure.

When a functional error is encountered, the data flow continues to perform the subsequent API calls until this number is reached. If this number is reached, the data flow stops and displays an error.

When this parameter is not set, the default value is -1 (no error limit).

The HTTP Error responses can be designed in the metadata and mapped into a target datastore.
An API call is considered a functional error if, after all the retries, it is still failing. See the Functional Retry Number parameter.

Functional Retry Number

This parameter specifies the number of retry attempts performed when there is a functional error, before giving up and continuing with the next API call.

When the amount of retry is reached without succeeding, the API call is considered a functional error, and the runtime proceeds with the next API call.

The number of retries is independent of the Functional Error Acceptance Number parameter.
An API call is considered as a functional error if all the retries fail.

Functional Retry Delay

This parameter specifies the delay in milliseconds to wait between each retry attempt when there is a functional error.

Technical Errors Parameters

Technical Error Acceptance Number

A technical error happens when the target API is unreachable when there is a technical error that avoids contacting the API.

This parameter defines the number of technical errors tolerated before considering the data flow as a failure.

When a technical error is encountered, the data flow continues to perform the subsequent API calls until this number is reached. If this number is reached, the data flow stops and displays an error.

When this parameter is not set, the default value is 0 (no error limit).

An API call is considered a technical error if, after all the retries, it is still failing. See Technical Retry Number parameter.

Technical Retry Number

This parameter specifies the number of retry attempts performed when there is a technical error, before giving up and continuing with the next API call.

When the amount of retry is reached without succeeding, the API call is considered a technical error, and the runtime proceeds with the next API call.

The number of retries is independent of the Technical Error Acceptance Number parameter.
An API call is considered as a technical error if all the retries fail.

Technical Retry Delay

This parameter specifies the delay in milliseconds to wait between each retry attempt when there is a technical error.