If you would like to upgrade to a newer long-term support version of Studio Pro, see Moving from Mendix Studio Pro 8 to 9.

Consume a REST Service

Last modified: August 19, 2024

Introduction

Mendix applications frequently need to communicate with existing systems. Whether you are creating an app to replace an older platform or a legacy system or want to integrate an existing database, the ability to integrate with existing systems is a necessary feature. In your Mendix app, you can use published REST services for this integration.

This how-to shows you how to do this using an example in which you create an app that retrieves Wikipedia pages from a REST service. The resulting app is available for download.

This how-to teaches you how to do the following:

Integrate with an existing system using a REST service
Call the REST service in a microflow

Creating a published REST service on top of the system you want to integrate with is outside the scope of this how-to; for instructions on how to do this, refer to the configuration of your non-Mendix Platform.

Creating a JSON Structure

If the system you want to integrate into your app has the functionality for exposing its data to REST services, you can integrate it easily into your Mendix app using consume REST service. Each system has a different JSON structure based on internal data models.

You are going to use the Wikipedia REST service as an example in this how-to. It allows you to retrieve the summary of a Wikipedia page – in this case information about a country. This service can be reached at https://en.wikipedia.org/api/rest_v1/page/summary/{title}, where {title} is the title of a page.

We will start by providing to Studio Pro an example of what the REST service returns:

Open your browser and go to https://en.wikipedia.org/api/rest_v1/page/summary/Tahiti.
This calls the REST service with a GET request – the result is the summary of the Tahiti page on Wikipedia in the JSON format:
Copy the whole JSON snippet. Make sure that you select the Raw Data tab to copy the whole code structure.
Create a module and name it RESTconsume. To add a new JSON structure to your module with the sample JSON that you can use in the app, right-click the module in the Project Explorer and select Add other > JSON structure.
Enter a Name for the structure: JSON_structure and click OK.
In the JSON Structure dialog box, paste the JSON snippet in the General tab and click Refresh. This analyzes the structure of the JSON snippet that we can use later.
Click OK.

Creating an Import Mapping

An import mapping specifies how the JSON relates to entities. You can map the JSON to any entity you like. The following steps describe how to generate the entities and create an import mapping:

Right-click the module in the Project Explorer and select Add other > Import Mapping.
Enter a Name for the import mapping: Import_mapping and click OK.
In the Select schema elements for import mapping dialog box, click the radio button for JSON structure and then click Select.
Double-click JSON_structure in the Select JSON Structure dialog box.
Click Expand all and then click Check all.
Click OK. The Import_mapping document is displayed and the JSON structure is on the right.
Click Map automatically in the editor toolbar.
A pop-up box is displayed informing you that can See the details for the changes that have been applied. You can click Details to see details of the mapping to the entities that are generated to match the JSON structure.
Click Close to see the entities corresponding to the JSON structure.

Adding an Input Entity to the Domain Model

The service takes the title of the page as an input and it returns the summary of the page from Wikipedia.

In this section, you will create an entity that represents this input and associate it with its summary.

To add an input entity to the domain model, follow these steps:

In the Project Explorer, double-click the Domain Model.
Rename Root to Summary.
From the Toolbox, drag an Entity into the domain model.
Double-click the entity and enter Input for the Name.
For Persistable, select No.
On the Attributes tab, click New to add a string attribute and name it Title.
Click OK.
Drag an association from Input to Summary.
Go to the Import_mapping and from the Connector pane drag Input as the input parameter for the input mapping.
Double-click Summary.
In the Map entity ‘Summary from the object element ‘Summary dialog box, Set association to Yes and select the RESTconsume_input_Summary for the Association to have the import mapping set the association:
Click OK.

Calling the REST Service in a Microflow

You will now call the REST service in a microflow to build the integration with Wikipedia. The microflow takes Input as the input parameter and sets the associated Summary.

To call the REST service in a microflow, follow these steps:

Right-click the module and select Add > Microflow and accept the default Name Microflow for the name of the microflow and click OK.
From the tool bar, drag a Parameter object to the microflow document.
Click Select for the Data type and select the Input entity as the input parameter. Click OK.
Right-click the mouse and select Insert > Activity to insert an activity to the microflow. Double-click the activity and select the Call REST service to change the activity.
In the Call REST dialog box, click Edit for the Location and add the following to Template: https://en.wikipedia.org/api/rest_v1/page/summary/{1}, with the parameter being the Title attribute from the Input parameter $Input/Title. Click OK.
In the Response tab, the response has to be mapped using the import mapping. For Response handling select Apply import mapping.
For Mapping, click Select and double-click Import_mapping. For the Parameter, select Input.
For Output select Yes for Store in variable and specify Summary for the Variable name.
Click OK.
Right-click after the Call REST service object and select Insert > Activity and double-click it and change it to a Change object.
For the Input Object, select Input (RESTconsume.Input).
For Refresh in client, select Yes. This ensures that the summary is displayed on the screen.
Click New.
On the Edit Change Item dialog box, for Member, select RESTconsume.Input_Summary (RESTconsume.Summary).
Under Value, enter $Summary.
Click OK.
Click OK. You have created microflow that takes the title of an article as input and associates it with its summary.

You have successfully consumed a REST service and created a microflow to show the results. The rest of this how-to describes how to use this microflow in an app so that you can see the REST call in action.

Creating a Page

To create a page for this app, follow these steps:

Open the **** and add a Data view.
Right-click the [Unknown] bar and click, Select entity. Select the Input entity.
For the Data source – Type, select Microflow.
For the Name, enter CreateInput. Note that when this page loads, it needs a new Input object – you will define the CreateInput microflow that creates this object in Filling In the Create Input Microflow.
Click OK.
From Container widgets, add a new Table with one row and two columns.
Drag the Title field onto the left column.
From the Project Explorer, drag Microflow into the right column.
Double-click the Microflow button and in the Edit Action Button dialog box, enter Get summary for the caption of the button.
Add a Data view below the table (inside the other data view).
From the Connector, drag the Summary entity onto the [Unknown] bar.
Click OK.
From this data view, delete all the fields except Extract.
Double-click Extract.
For Show label, select No.
Click OK.
Delete the Save and Cancel buttons.

Filling In the Create Input Microflow

Now all that is left is to have the CreateInput microflow create a new Input object.

To fill in the CreateInput microflow, follow these steps:

In the Project Explorer, double-click CreateInput.
From the Toolbox, drag a Create object activity to the microflow.
Double-click the activity.
For Entity, click Select and double-click Input, then click OK.
Double-click the red End event.
Under Return value, enter $NewInput, then click OK

Congratulations! You can now start your app and get summaries from Wikipedia.

Example

How to consume REST with Mendix Studio Pro 8

For Studio Pro v 8.15 and above, the Call REST dialog box has changed from what is shown in the video. You have to ensure that for Output you select Yes for Store in variable and then specify the Variable name.