Publish a REST Service

Last modified: March 8, 2024

1 Introduction

Mendix allows you to publish REST web services natively from Studio Pro. This how-to explains how to publish a REST service in an example project and demonstrates 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

2 Prerequisites

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

3 Setting Up the Example App

To set up the example app that you will use in the next sections for publishing your REST service, follow these steps:

  1. Create a new app and rename the MyFirstModule module to RESTExample.

  2. Open the domain model of the RESTExample module.

  3. Create OrderItem and Order entities with a many-to-one association, like this:

    Many-to-one association from OrderItem to Order
  4. Generate overview and detail pages for the Order and OrderItem entities.

  5. Add a data grid to the Order_NewEdit page. Set it to display the OrderItem objects from the database over an association, like this:

    Data grid settings for the Order_NewEdit page

Your completed Order_Overview page should look like this:

Structure mode view of the Order_NewEdit page with data grid

Add the overview page to your app navigation. Then, run the application and create a couple of orders and order items.

4 Publishing the Service

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

4.1 Creating the Mapping

To create the mapping, follow these steps:

  1. In the App Explorer, right-click the RESTExample module and select Add other > Message definitions.

  2. In the Add Message Definitions dialog box, enter MD_Orders in the Name field. Click OK to create and start editing the new message definition.

  3. Select Add to open the Message Definition dialog box.

  4. Click Select and choose the Order entity from the list. Selecting the entity fills in the Structure part of the Message definition dialog box. By default, only the Order checkbox is selected.

  5. Select the OrderID and Customer attributes.

  6. Select and expand the OrderItem_Order association, then select the Product and Quantity attributes:

    Checkbox selections in the Message Definition 'Order' dialog box
  7. Click OK to close the dialog box.

  8. Save and close the MD_Orders message definition.

4.2 Configuring the REST Service

  1. In the App Explorer, right-click the RESTExample module and select Add other > Published REST Service.

  2. Enter PRS_OrderService for the Name of your REST service. Then press OK to create and start editing the new REST service.

  3. Add a new resource to your service by clicking Add in the Resources field. Enter GetOrderByID for the Resource name, then click OK.

    Adding a GetOrderByID resource
  4. Add an operation to your resource by clicking Add in the Operations for resource field.

  5. In the Operation dialog box, enter {OrderID} in the Operation path field, making sure to include the braces ({}). This allows the REST service to be invoked with the order ID in the URL shown in the Example location field of the dialog box.

    {OrderID} in the Operation path field
  6. In the same dialog box, click Select next to the Microflow field. You do not yet have a microflow for this operation, so select the RESTExample module in the dialog box and click New to create a new microflow. Enter PRS_GetGetOrderByID for the Name of this new microflow, then click OK.

  7. In the Parameters field of the same Operation dialog box, click Add and add an OrderID path parameter.

    Operation path, microflow, and parameter settings
  8. Click OK to close out the Operation dialog box, then click Show to start editing the newly created microflow. Add a OrderID parameter.

  9. Add a Create variable activity to the microflow to convert the OrderID variable from data type String to Integer/Long. This makes it possible to search for the OrderID (an AutoNumber data type).

    Create Variable dialog box used to parse OrderID as an integer variable
  10. Add a Retrieve activity to the microflow to retrieve the Order based on the OrderID. Set this activity to retrieve the first matching order from the database.

    Range and XPath constraint settings in the Retrieve Objects dialog box

4.2.1 Building an Export Mapping (optional)

The next steps explain how to ensure that outputs are generated in JSON. You can do this using Export Mappings or in a microflow. Creating an export mapping is not required because published REST services in Studio Pro support content negotiation, which means the REST services let you select which media type you want to be returned to the server.

To build an export mapping, follow these steps:

  1. Right-click the RESTExample module on the App Explorer and select Add other > Export mapping to add a new export mapping named EM_ExportOrder.

  2. In the Select schema elements for export mapping dialog box, select Message definition. Then, click Select to choose Order from the MD_Orders mapping you created earlier. Select all the attributes, as shown below, and click OK.

    All attribute checkboxes selected in the Select schema elements for export mapping dialog
  3. In the export mapping that is shown, map the schema object elements to the matching entities from the domain model by either double-clicking the schema object elements or dragging the entities from the Connector pane. Make sure to map the attributes with the same names. Your mapping should look like this:

    Mapping Order to Order and OrderItem to OrderItem
  4. Go back to the PRS_GetGetOrderByID microflow and add an Export with mapping activity.

  5. In the Mapping field of the dialog box, select the EM_ExportOrder mapping. In the Parameter field, select the Order object that was retrieved with the Retrieve action in the microflow.

  6. Select JSON for the result, and store the output in a String Variable. Enter Order_JSON for the Variable name.

    Export With Mapping dialog box settings
  7. Add a Create object activity to the microflow to create an object of type HttpResponse. Create three new members:

    • A StatusCode that returns the value 200 to indicate success
    • Content mapped to the exported JSON from the previous step
    • The HttpVersion that you will be using ('HTTP/1.1' in this case)
    Create Object dialog box for HttpResponse object
  8. Add a Create object activity to the microflow to create an object of type HttpHeader. Create three new members:

    • Key, set to 'Content-Type'
    • Value, set to 'application/json' (or 'application/xml' if your response contains XML rather than JSON)
    • System.HttpHeaders, set to your HTTP response ($NewHttpResponse).
    Create Object dialog for HttpHeader
  9. Open the End Event in your microflow and enter $NewHttpResponse as the return value. Your completed microflow should look like this:

    Completed PRS_GetGetOrderByID microflow

4.3 Viewing the App

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

  1. Run your app and open it in the browser using this URL: http://localhost:8080/rest-doc/.

  2. You will see a page with the documentation of all your published REST services. Click the PRS_OrderService link to view the details:

    Details for the PRS_OrderService
  3. Click GET. Then, click Try it out and enter an OrderID.

    OrderID with Description input field
  4. Click Execute to run the request and return the result in the Response body.

    Result in Response

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

5 Error Handling

You have not yet implemented error handling in this new service. For example, if you enter text instead of an integer in the OrderID parameter (or if you leave it blank) before clicking Execute, you will see a generic 500 or 404 error. To publish a more robust service, implement error handling.

5.1 Adding Error Handling

  1. Open the PRS_GetGetOrderByID microflow and right-click the first activity. Select Set error handling > Custom with rollback > OK.

  2. Hover your mouse over the error handling flow. Click the blue circle and select Create object.

  3. Create a new HttpResponse object and enter NewHttpErrorResponse for the Name. Then, map the attributes as shown below:

    Create Object dialog box for NewHttpErrorResponse
  4. Hover your mouse over the next error handling flow, click the blue dot, and add another Create object activity to create a new httpHeader object. Map the attributes as shown below:

    Create Object dialog box for NewHttpHeader_1
  5. Add an End Event and set $NewHttpErrorResponse as its return value. Your microflow should look like this:

    Updated microflow with error handling
  6. Test your error handler, as you did with the app in the Viewing the App section. Enter some text in the OrderID parameter, click Execute, and observe the request’s response:

    Error in server response

5.2 Additional Error Handling

Now that you have covered the OrderID parameter error handling, it is time to handle empty responses. Empty responses are not technically errors, but it is good practice to indicate what happened when nothing is returned. To add error handling for the situations when the OrderID parameter is filled with a valid integer but no corresponding Order result is found in the database, follow these steps:

  1. After the Retrieve order from database activity, add a decision activity with the following expression: $Order != empty. Connect the true exit to the activity for exporting to JSON. For the false exit, add a new Create object activity that creates a NewHttpErrorNotFoundResponse object.

    Create Object dialog box for NewHttpErrorNotFoundResponse
  2. Add an activity to create a NewHttpErrorNotFoundHeader object.

    Create Object dialog box for NewHttpErrorNotFoundHeader
  3. Configure the End Event to return $NewHttpErrorNotFoundResponse. The microflow should look like this:

    Updated microflow with decision activity and false exit
  4. Test your new error responses, as you did with the app in the Viewing the App section.

6 Read More

  • Published REST Services – Information on creating published REST services in Mendix (including GET, POST, and DELETE operations)