Expose a Web Service

Last modified: August 20, 2024

Introduction

Mendix supports many ways to expose the functionality and data of your application to others. The easiest way is to use web services. A web service can contain multiple operations.

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

  • Create a web service
  • Publish a microflow as web service operation

Prerequisites

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

Data Structure and GUI

  1. Create the following Customer entity in your domain model (for details on how to create an entity, see Create a Basic Data Layer):

  2. Create overview and detail pages to manage objects of the Customer type (for details on how to create overview and detail pages, see How to Create Your First Two Overview and Detail Pages.

  3. Create a menu item to access the customer overview page (for details on how to create menu items, see Setting Up Navigation.

  4. Run the application and add some data to expose in the web service.

Creating a Published Web Service

To create a published web service, follow these steps:

  1. Right-click the module in which you want to store the published web service and select Add other > Published web service.

  2. In the Add Published Web Service window, enter CustomerWebService for the Name and then click OK:

  3. You should now see the Published Web Service properties window. Take note of the following tab details:

    • On the Operations tab, you can see the available operations of the web service (currently the list is empty, so we’ll add an operation in section Publishing a Microflow):

    • On the Settings tab, you can configure the other settings. Do change them before publishing your web service, especially the Target namespace (for details on these settings, see Published Web Service in the Studio Pro Guide):

  4. Click OK.

Creating the Functionality to Expose

To create the functionality to expose, follow these steps:

  1. Create a microflow that retrieves and returns a list of customers from the database (for details on how to create a microflow, see Triggering a Microflow From a Menu Item).

  2. To make the microflow more exciting, add two input parameters to dynamically set the range settings of the retrieve action. Configure the range options of the retrieve action like this:

    Reference this microflow:

If you get any errors, you will need to mark the input parameters in the Operations > Paremeters section of the service document as Optional and Nillable (see the following section.)

Publishing a Microflow

To publish a microflow, follow these steps:

  1. Right-click somewhere in the background of the microflow and select Publish as Web service operation:

  2. Locate the web service created in Creating a Published Web Service and click Select:

  3. You should now see the Operation Operation properties editor. Take note of the following tab details:

    • On the General tab, you can change the Name and Documentation.
    • On the Parameters tab, you can mark the input parameters as Optional and Nillable (needed when adding parameters during the creating the functionality to expose step)
    • On the Return type tab you can configure the return type.

  4. Click Select… to select which attributes and associations of the return object Customer you want to expose:

  5. Select the members you want to expose and click OK. Only the selected members will be returned by the web service.

  6. Click OK to save the operation.

Getting a WSDL

You need a Web Services Description Language (WSDL) to allow others to interact with the web service you just created. The WSDL describes how to call the operations in the web service.

To get a WSDL, follow these steps:

  1. Run the application locally or in a Free App environment.

  2. View the application in your browser:

    • If you run the application locally, the application URL should look like this: http://localhost:8080/index.html
    • If you run the application in a Free App environment, the application URL should look like this: https://myfirstapp.mendixcloud.com/index.html

  3. In both of the above cases, you can replace /index.html with /ws-doc/ to open the web service documentation page:

    You should see the name of your web service in the list.

  4. Click the “WSDL schema” URL to open the WSDL. This WSDL can be given to others so that they can interact with your web service.

Authentication and Users

To change the user authentication, follow these steps:

  1. Double-click the published web service in the App Explorer to open it.

  2. In the Published Web Service properties window, open the Settings tab. Because No Authentication is set, currently users of the web service do not need to authenticate:

  3. Change Authentication to Username and password.

  4. Click OK and re-run the application. Users now need to authenticate before they can use the web service.

Mendix enables creating your own user management functionality as long as your own user object inherits from System.User. The User entity in the System module contains the WebServiceUser Boolean attribute. This attribute determines if an user is able to interact with web services. If you want a certain user to be able to interact with web services, the value of this attribute must be true.

Considerations

When exposing a web service, consider the following things:

  • In Studio Pro some words are reserved for Mendix use (for example, type, Enumeration)
  • Because you may not want to publish a “_type” attribute with an underscore ("_") in front of it, you can change the WSDL name by changing the last column in the selected attribute window
  • If an attribute is renamed after it is published, the name in the WSDL does not automatically change (because that would break the customer’s implementation)

Read More