Call REST Service

Introduction

The Call REST service activity can be used to call a REST endpoint. You can specify the location and how the response of the REST call should be handled.

Properties

An example of call rest action properties is represented in the image below:

There are two sets of properties for this activity, those in the dialog box on the left, and those in the properties pane on the right.

The call rest action properties pane consists of the following sections:

• Action
• Common

Action Section

The Action section of the properties pane shows the action associated with this activity.

You can open a dialog box to configure this action by clicking the ellipsis (…) next to the action.

You can also open the dialog box by double-clicking the activity in the microflow or right-clicking the activity and selecting Properties.

The properties dialog box consists of four tabs:

• General
• HTTP Headers
• Request
• Response

General Tab

Location

The Location property defines the REST endpoint to be called.

The location needs to be entered using a string template which must result in a valid URL string.

String Template

The template for the location can contain parameters that are written as a number between braces (for example, {1}). The first parameter has the number 1, the second 2, etc. You can escape the opening brace ({), by using a double opening brace ({{).

Parameters

For each parameter in the template, you can specify its value using a microflow expression resulting in a string value. This value will be inserted at the position of the parameter.

HTTP Method

The HTTP method property defines the HTTP method to use when calling a REST endpoint. The possible values are: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.

Use Timeout on Request

Set Use timeout on request to Yes to be able specify how long the Call REST activity should wait for the REST endpoint to respond.

Default value: Yes (as of Studio Pro 8.5.0; in earlier versions, the default value was No)

Timeout (s)

If the REST endpoint has not responded after the number of seconds in Timeout (s), an exception will occur and the microflow will roll back or go into your custom error handler.

Default value: 300 seconds (as of Studio Pro 8.5.0; in earlier versions, the default value for Use timeone on request was No)

Proxy Configuration

In almost all cases, you can ignore this setting. Use project settings is a good default value.

If desired, you can configure whether to use a proxy for the request. These are the choices:

• Use project settings – use whatever settings are defined at the project level (default)
• Override – override the project-level settings for this action
• No proxy – do not use a proxy for this action, even if there is a proxy configured at the project level

When you select Override, you can configure dynamically whether to use a proxy. You then supply the host, port, username, and password settings for the proxy.

Client certificate

In most cases, the default Use project settings can be used.

However, you can specify a client certificate to use for the request by clicking override. Select from one of the following:

• Use project settings(default) – use the settings that are defined at the project level
• Override – override the project-level settings for this action

When you select Override, you can configure the client certificate that will be used. Click Edit to specify the Client certificate identifier. This identifier can be set in different places, depending on where you deploy the app:

• When you deploy the app to Mendix Cloud, the identifier is set when pinning a client certificate
• When you deploy the app elsewhere, the identifier is set in the custom setting ClientCertificateUsages

When this identifier is not set (either not pinned or not present in ClientCertificateUsages), the default settings will be used (as if Use project settings were selected).

HTTP Headers Tab

Use HTTP Authentication

The Use HTTP authentication checkbox defines whether basic authentication should be used.

User Name

The User name property defines the user name that will be used to authenticate over HTTP. The user name needs to be entered using microflow Expressions. The microflow expression should result in a string.

Password

The Password property defines the password that will be used to authenticate over HTTP. The password needs to be entered using expressions. The microflow expression should result in a string.

Custom HTTP Headers

These headers are added to the HTTP request header. Each custom header is a pair with a key and a value (a microflow expression).

Request Tab

The sections below describe the options in the drop-down menu for generating the request.

Export Mapping for the Entire Request

This option allows you to use a single export mapping for the body of the request.

Mapping

Select the mapping that you want to apply.

Parameter Type

If the export mapping requires an input, this field shows the type of the input.

Parameter

If the export mapping requires an input, you can select a parameter of the correct type.

Content Type

If the export mapping is based on a message definition, it can export either XML or JSON. Choose the type of output you want.

Binary for the Entire Request

This option allows you to send binary data (for example, the contents of a FileDocument).

Form-Data

This option allows you to generate a multipart/form-data request for multiple parts. Each part is a pair with a key and a value (microflow expression).

FileDocuments and images are also supported for this option when used as variables in microflow expressions.

Content Type

Setting up a Content-Type header for a form-data request will result in a consistency error, as it will automatically be set to multipart/form-data.

The content type for the FileDocument part is application/octet-stream.

Custom Request Template

This option allows you to generate the request using a string template. The template defines the structure of the request in plain text.

See String Template, above, for more information on constructing strings from templates.

Response Tab

Response Handling

These are the options in the drop-down menu for handling the response:

• Apply import mapping – if the response is JSON or XML, it can be transformed directly into objects using an import mapping; the fields that you can choose here are described in the Import Mapping action
• Store in an HTTP response – any successful HTTP response can be stored directly in an HttpResponse object, and the $latestHttpResponse variable is also updated
• Store in a file document – if the response contains binary content (for example, a PDF), it can be stored in an object of an entity type which inherits from System.FileDocument
• Store in a string – if the response is a string (for example, CSV), it can be stored directly in a string variable
• Do not store in a variable - use this option when the call does not return anything useful

Type

The Type field defines the type of the output.

Variable

The Variable field defines the name for the result of the operation.

$latestHttpResponse Variable

The $latestHttpResponse variable is of the HttpResponse type. It is available after a Call REST activity.

However, its Content attribute will be left empty in most cases to minimize memory usage.

This attribute is filled when one of the following scenarios occur:

• The Response handling is Store in an HTTP response and the call succeeded
• The Store message body in $latestHttpResponse variable option in the Error handling section is checked and the call failed

This variable can be accessed from any microflow action in the scope.

Store Message Body in $latestHttpResponse Variable

If HTTP response status code is not successful (for example, [4xx] or [5xx]), the flow will continue in an error handler.

Common Section