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.

Publish a REST Service

Last modified: August 19, 2024

Introduction

Mendix allows you to publish REST web services natively from Studio Pro. This how-to will show you how to publish a REST service in an example project. This example will demonstrate the GET operation for a published REST service.

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

Create a published REST service and return the results in JSON or XML

Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

Install Studio Pro

Setting Up the Example Project

To create the example project you will use in the next sections for publishing your REST service, follow these steps:

Create a new app and rename the MyFirstModule module to RESTExample.
Open the domain model of the RESTExample module.
Create entities with an association like this:
You need pages for entering order data, so create an overview page for the Order entity In the RESTExample module.
Create a NewEdit page for the orders, then add a data grid to the Order_NewEdit page that displays the OrderItems over an association.

Your page should now look like this:

Add the overview page to your project navigation and run the application. Create a couple of orders and order lines by filling in the appropriate fields.

Publishing the Service

To be able to use the data from your model in the REST service, you need to create a message definition.

Creating the Mapping

In the Project Explorer, right-click the RESTExample module and select Add > Mappings > Message Definitions:
In the Add Message Definition dialog box, enter MD_Orders as the name for this definition.
The message definition is now opened and you need to select the entity to use for the MD_Orders definition. To do this, select Add and in the dialog box, click Select, then choose the Order entity from the list.
After selecting the Order entity, the Structure part of the dialog box is filled with only the Order object selected.
Select the OrderID and Customer attributes
Expand the OrderItem_Order association and select the Product and Quantity attributes:
Click OK to close the dialog box.
Close the message definition, and make sure to save the definition if asked!

Configuring the REST Service

In the Project Explorer, right-click the RESTExample module and select Add > Published Services > Published REST Service:
Enter PRS_OrderService for the Name of your REST service. The REST service is now opened
Add a new resource to your service by clicking Add, and enter GetOrderByID for the Resource name:

Click OK to close the dialog box.
Add an operation to your resource by clicking Add in the Operations for resource section.
In the Operation dialog box, enter{OrderID} in the Operation path field (make sure to include the braces). This will allow the REST service to be invoked with the OrderID in the URL shown in the Example location field of this same dialog box.
In the same dialog box, click Select next to the Microflow field. As you do not have a microflow for this operation, select the RESTExample module in the dialog box and then click New to create a new microflow. Enter PRS_GetGetOrderByID for the Name of this new microflow:
Click Show to start editing the newly created microflow.
Add two parameters: httpRequest and OrderID.
Add an action to the microflow to convert the OrderID variable (string) to an integer variable. This is needed to be able to search for the OrderID (autonumber).
Add a second activity to the microflow to retrieve the Order based on the OrderID. This retrieve action from the database returns 1 order.
From the Project Explorer, right-click the RESTExample module and select Add > Mappings > Export Mapping to add a new mapping named EM_ExportOrder:
In the Select schema elements for export mapping dialog box, select the Message definition option, and then select the MD_Orders mapping created earlier via the Select button:

Make sure to select all the attributes a shown above, then click OK.
In the export mapping that is shown, map the objects to the same objects from the domain model (either by double-clicking or dragging from the Connector pane). Make sure to map the attributes with the same names. Your mapping should look like this:
Now go back to the PRS_GetGetOrderByID microflow and add an Export with mapping activity.
In the Mapping field of the dialog box, select the mapping created above in step 11. For the Parameter field, select the Order object retrieved with the database retrieve action in the microflow.
Select JSON for the result, and store the output in a String variable. Enter Order_JSON for the variable’s Name.
Add an activity to the microflow to create an object of the type HttpResponse:

The StatusCode will return “OK” as a 200 message. The content of the message is mapped to the exported JSON from step 16. And add the HttpVersion that you will be using (in this case, HTTP/1.1).
Add an activity to the microflow for adding a header to the response:

Set the member Key to 'Content-Type' and the Value to 'application/json'(or 'application/xml' if your response contains XML rather than JSON). Set the System.HttpHeaders association to your HTTP response.
Open the end activity in your microflow and select $NewHttpResponse as the return value. You should have no errors, and your microflow should look like this:

Viewing the App

To view and try out your app, follow these steps:

Run your app and open it in the browser via this URL: http://localhost:8080/rest-doc/.
You will see a page with the documentation of all your published REST services:
Click the PRS_OrderService link to view the details:
Click GET followed by Try it out.
Fill in a OrderID and click Execute:

This will execute the request and return the result in the Response body:

Cool! You have published your first REST service from Mendix.

Error Handling

In this new service, no error handling has been implemented. For example, if you now execute your service and enter a string in the OrderID parameter (or leave it out), you will see a 500 or a 404 generic error. So, error handling should be implemented to publish a robust service.

Adding Error Handling

Open the PRS_GetGetOrderByID microflow, right-click the first activity, then select the option to Set Error Handling to Custom with rollback.
After the first activity, add an activity that creates a new HttpResponse object. Enter NewHttpErrorResponse for the Name, and map the attributes like this:

For the Content member, the value is this JSON string: '{"Error": "The OrderID can only be an integer"}'.
Set the new activity as the custom error handler.
Below this activity, add a Create object activity that creates a new httpHeader object:

Make sure to associate the header to the NewHttpErrorResponse.
Add a new endpoint for the microflow and set NewHttpErrorResponse as the return value. Your microflow should now look like this:
Test your error handler as you did with the app in section 4.3 Viewing the App. Enter some characters in the OrderID parameter and observe the response of the request, like this:

Additional Error Handling

Now that you covered the error handling of the parameter parsing, it’s time to handle empty responses. This is not really an error, but an indication of what happened when nothing was returned is always a good idea.

To add the error handling for those situations when the OrderID parameter is filled but no result is found, follow these steps:

After the activity for retrieving from the database, add a decision activity with the following statement: $Order != empty. The true exit is connected to the activity for exporting to JSON. For the false exit, add new create object activities that create a NewhttpErrorNotFoundResponse and a NewhttpErrorNotFoundHeader:

The Content is filled with the following string: '{"Error": "No Order available for ID:'+$OrderID+'"}'.
Configure the end activity to return the NewHttpResponse. The microflow should now look like this:
Test your new error responses as you did with the app in section 4.3 Viewing the App.