Published REST Service

Last update: Download PDF Edit

1 Introduction

Use a published REST service to expose your entities and microflows to other apps using the REST standard.

2 General

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.

2.2 Version

Version is used to display version information in OpenAPI (Swagger) documentation page. You can set any string in the version field, but it is recomended to follow semantic versioning scheme.

By default, version is set to “1.0.0”.

2.3 Location

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.

Example:

http//localhost:8080/rest/my_service_name/v1

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:

  • ws/
  • ws-doc/
  • rest-doc/
  • odata/
  • odata-doc/
  • api-doc/
  • xas/
  • p/
  • reload/

When your application is running, you can click the location to open the interactive documentation page.

2.3 Public Documentation

The public documentation is used in the service’s OpenAPI 2.0 (Swagger) Documentation. You can use GitHub-flavored markdown for rich text.

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 /rest-doc/servicename/swagger.json.

3 Security

3.1 Requires Authentication

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”)
  • Select Active session to allow access from JavaScript inside your current application

    • Once a user has logged into the browser, the JavaScript in your app can access the REST service using the current user’s session
    • To prevent cross-site request forgery, the X-Csrf-Token header 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);

3.3 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.

4 Resources

A REST service exposes a number of resources. On a resource you can define GET, PUT, POST, PATCH, DELETE, HEAD and OPTIONS operations.

5 Operations

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.

6 Example

How to publish REST natively with Mendix

For more information on which operation gets executed for a given request URL, see Published REST Routing.