The published REST service feature was introduced in version 7.10.0.
Use a published REST service to expose your entities and microflows to other apps using the REST standard.
This document describes the published REST service configuration options shown when the published REST service is opened in the Desktop Modeler.
2.1 Service Name
Service name uniquely identifies the service in the app. It is also displayed in OpenAPI (Swagger) documentation page.
When service is initially created, service name is used in the creation of the default location for the service. If the service name contains any spaces or special characters, they will be replaced with the
_ character in the service location.
The Version feature was introduced in version 7.12.0.
By default, version is set to “1.0.0”.
Location is editable in Mendix versions 7.12.0 and above.
Location shows URL on which a service can be reached.
By default, location is built up by appending service name and “v1” to the “rest/” prefix. Service name will be stripped off of any invalid URL characters; like spaces and special characters.
You can change the the default location to almost any valid URL.
2.3.1 Reserved Prefixes
Following URL prefixes are reserved and are not allowed to be used in location:
When your application is running, you can click the location to open the interactive documentation page.
2.3 Public Documentation
2.5 Export swagger.json
To save a service’s OpenAPI (Swagger) documentation somewhere on your machine, simply right-click the service in the Project Explorer and select Export swagger.json (or just click the Export swagger.json button, depending on your Modeler version). This is a machine-readable file in the OpenAPI 2.0 file format. Most API tools support this format.
When the app is running, this file is available under
3.1 Requires Authentication
The No Authentication feature was introduced in version 7.11.0. In earlier versions, it was always Username and password.
The Active Session authentication was introduced in version 7.13.0
The Custom authentication was introduced in version 7.17.0
Select whether clients need to authenticate or not.
3.2 Authentication Methods
If authentication is required, you can select which authentication methods you would like to support
- Select Username and password to allow clients to authenticate themselves using a username and a password in the Authorization header (this is called “basic authentication”)
- To prevent cross-site request forgery, the
X-Csrf-Tokenheader needs to be set on each request, for example:
var xmlHttp = new XMLHttpRequest(); xmlHttp.open("GET", "http://mysite/rest/myservice/myresource", false); xmlHttp.setRequestHeader("X-Csrf-Token", mx.session.getConfig("csrftoken")); xmlHttp.send(null);
Select Custom to authenticate using a microflow. This microflow is called every time a user want to access a resource.
Check more than one authentication method to have the service try each of them. It will first try Custom authentication, then Username and password, and then Active session. For more details, see Published REST Routing.
Specify which microflow to use for custom authentication.
Select Parameters to see the list of parameters passed to the authentication microflow. In that window you can indicate whether the authentication microflow’s parameters come from request headers or from the query string.
The microflow may take an HttpRequest as a parameter, so it can inspect the incoming request.
The microflow may also take an HttpResponse as a parameter. When the microflow sets the status code of this response to something other then 200, this value is returned and the operation will not be executed. Any headers set on the response are returned (except when the microflow returns an empty user).
The authentication microflow should return a User.
There are three possible outcomes of the authentication microflow * When the status code of the HttpResponse parameter is set to something other then 200, then this value is returned and the operation will not be executed * Otherwise, when the resulting User is not empty, the operation is executed in the context of that user * Otherwise, when the resulting User is empty, the next authentication method is attempted. When there are no other authentication methods, the result is 404 Not Found.
3.4 Allowed Roles
The allowed roles define which module role a user must have to be able to access the service. This option is only available when Requires authentication is set to Yes.
Web service users cannot access REST services.
4 Enable CORS
Check this box when your service needs to be available on websites other than your own.
Click the Settings button to specify this access in more detail (for instance, which websites are allowed to access the service).
A REST service exposes a number of resources. On a resource you can define GET, PUT, POST, PATCH, DELETE, HEAD and OPTIONS operations.
You can drag an entity or a message definition onto this list to generate a complete resource.
When you select a resource, you see the operations that are defined for that resource.
Resources and Operations are appended to Location to form a URL on which they can be accessed.
How to publish REST natively with Mendix
8 Read More
For more information on which operation gets executed for a given request URL, see Published REST Routing.