Published REST Service

Last modified: November 21, 2024

Introduction

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 Studio Pro.

General

Service Name

The service name uniquely identifies the service in the app. It is also displayed in OpenAPI (Swagger) documentation page.

When a 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.

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 recommended to follow semantic versioning scheme.

By default, version is set to “1.0.0”.

Location

Location shows the 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 any invalid URL characters, such as spaces and special characters.

Example:

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

The URL prefixes api-doc/, xas/, p/, and reload/ are reserved and cannot be used at the start of the location. Otherwise, you can change the location to any valid URL.

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

Public Documentation

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

Export OpenAPI Documentation

To save a service’s OpenAPI (Swagger) documentation on your machine, right-click the service in the App Explorer and select Export openapi.json for the OpenAPI 3.0 definition of the REST service, or select Export swagger.json (or just click the Export swagger.json button, depending on your Studio Pro version) for the OpenAPI 2.0 version. These are machine-readable files according to the OpenAPI Specification format. Most API tools support this format.

When the app is running, these files are available under /rest-doc/{location}/openapi.json and /rest-doc/{location}/swagger.json, where {location} is the location of the REST service (for instance, rest/myservice/v1).

Security

Requires Authentication

Select if clients need to authenticate or not.

Authentication Methods

If authentication is required, you can select which authentication methods to support.

  • Select Username and password to allow clients to authenticate themselves using a username and a password in the Authorization header (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

  • Offline-first apps cannot use active session authentication, because they do not have sessions that stay active while the app is running

  • 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);

  • Select Custom to authenticate using a microflow. This microflow is called every time a user wants 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.

Microflow

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 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. In that case, any headers set on the response are returned as well.

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 than 200, this value is returned and the operation will not be executed.
  • When the resulting User is not empty, the operation is executed in the context of that user.
  • 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.

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.

Enable CORS

Check this box when your service needs to be available on websites other than your own.

Click Settings to specify this access in more detail (for example, which websites are allowed to access the service).

Resources

A REST service exposes a number of resources. On a resource, you can define the following operations:

  • GET
  • PUT
  • POST
  • PATCH
  • DELETE
  • HEAD
  • OPTIONS

You can drag an entity or a message definition onto this list to generate a complete resource.

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.

Read More

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