Published OData Services

Last modified: March 22, 2024

1 Introduction

In Studio Pro, entities can be exposed as OData resources by adding them to a published OData service. You can expose any number of related resources in a published OData service. By default, the plural of the non-qualified names of entities are used in the URI to uniquely identify them, but you can override the name of the resource as well.

A published OData service is a REST service with an OpenAPI contract, which means that OpenAPI compatible REST clients can easily interact with it.

The standards used for OData in Mendix are:

  • OData v3, which returns data in Atom XML format.
  • OData v4, which returns data in JSON format.

Not all parts of the standard are implemented. If something is not documented here, it is has not yet been added.

This document describes the options available to you when you create a published OData service, and ends with some runtime considerations.

2 General

2.1 Service Name

The service name uniquely identifies the published OData service within the app.

2.2 Version

Use the Version field to assign a version number to the service. This number will be shown in the API documentation.

2.3 Location

The location denotes where the service will be available. The part before /odata/ may be different depending on where the app is running. You can specify the part after /odata/ yourself. It is recommended to specify the service name and the major version in the location.

2.4 Namespace

In OData, the namespace is used to refer to data types. You can customize this namespace, changing it to any value which starts with a letter followed by letters, digits, or dots with a maximum length of 512 characters.

2.5 Entities

This list gives an overview of all entities published as OData resources.

2.5.1 Entity Details

This list gives an overview of all published attributes and associations.

2.6 Enumerations

This list gives an overview of all enumerations that are published by the service (for OData v4 only). When a published entity has an attribute with an enumeration type then the enumeration appears in this list. The list does not appear when there are no published enumerations. There is no need to add enumerations yourself, because Studio Pro will add them when needed.

Click Edit to change the exposed name of the enumeration (the name as it appears to clients of the service) and to provide documentation.

2.6.1 Enumeration Details

This list gives an overview of the values of the published enumeration.

Click Edit to change the exposed name of the enumeration value (the name as it appears to clients of the service) and to provide documentation.

Use the Refresh button when the enumeration values have changed to update the list with the new values.

3 Settings

3.1 Configuration

3.1.1 OData Version

You can choose between OData 4 (recommended) and OData 3. One of the main differences is that OData 4 services return results in JSON, and OData 3 services return results in XML.

3.1.2 Associations

You can select how you want to represent associations. For more information, see the Associations section of OData Representation.

3.2 Export

In this section, you can save the different representations of the service to file.

3.2.1 Service feed

The service feed, available in XML and JSON, contains a list of the published entities.

3.2.2 Metadata

The $metadata XML file contains the service’s contract in OData’s CSDL format.

3.2.3 OpenAPI

The OpenAPI JSON file contains the service’s REST contract in OpenAPI 3.0 format.

3.3 Security

You can configure security for the OData service when App Security is enabled.

3.3.1 Requires Authentication

Select whether clients need to authenticate or not. Select No to allow access to the resources without restrictions. Select Yes to be able to select which authentication methods to support.

Even when you choose Yes, you can still expose OData resources to anonymous users. For detailed information on allowing anonymous users, see Anonymous User Role.

3.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
  • 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.

3.3.2.1 Username and Password

Authentication can be done by including basic authentication in the HTTP header of the call. To do this you need to construct a header called Authorization and its content should be constructed as follows:

  1. Username and password are combined into a string “username:password”.
  2. The resulting string is then encoded using the RFC2045-MIME variant of Base64 (except not limited to 76 char/line).
  3. The authorization method and a single space (meaning, “Basic " is then put before the encoded string).

This result is a header which looks like Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==.

3.3.2.2 Active Session

When you check this authentication method, 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:

1
2
3
4

var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", "http://mysite/odata/myservice/myresource", false);
xmlHttp.setRequestHeader("X-Csrf-Token", mx.session.getConfig("csrftoken"));
xmlHttp.send(null);
3.3.2.3 Custom

Specify which microflow to use for custom authentication.

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, 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)
3.3.2.3.1 Mendix SSO

You can configure a published OData service to authenticate with the Mendix SSO module. This is a form of Custom authentication.

To set up authentication with Mendix SSO, do the following:

  1. Ensure that the Mendix SSO module has been installed and configured in your app.
  2. In the published OData service, choose Custom authentication and select the AuthorizeRequestWithAccessTokenFrom Request microflow.

3.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 Public Documentation

In the Public documentation tab, you can write a summary and a description intended for people using the service.

5 Properties

In the properties pane when an OData service document is displayed, you can edit some of the values that you can also set in the General tab, such as Service name, Version, and Namespace.

This section describes the additional values that you can set.

5.1 Documentation

Here you can add a description of the service. This is available to other users working on this app and is not published when the OData service is deployed.

5.2 Replace Illegal XML Characters

Some special characters cannot be used in XML. If your data contains these characters, the client will get an error. If you set this setting to Yes, those illegal characters are replaced by the DEL character, and the client will not get an error. However, the data that the client receives will not be exactly what is stored in your database, because these characters have been replaced.

This Replace Illegal XML Characters option is not available when the OData version is OData 4, because OData 4 returns data in JSON format.

Default value: No

6 Runtime Considerations

6.1 General

Once your app is published, a list of the published OData services will be available on the root URL of the app followed by /odata-doc/. For example, http://localhost:8080/odata-doc/. For each OData 4 service, there is a link to a Swagger UI page that shows an interactive documentation page on which users can interact with the service.

For details on how to filter the OData response, refer to OData Query Options.

For details on how Mendix attributes are represented in OData, refer to OData Representation.

When exposing entities through OData, the entities are retrieved from the Mendix database in a streaming fashion, to avoid out-of-memory errors in the Mendix Runtime.

6.2 On-Premises Deployments

Some on-premises servers, in particular those using Microsoft IIS, will strip the host header from requests. This means that your OData service and documentation will be published on an unexpected URL.

To resolve this issue, you will need to ensure your server preserves host headers. See the section Preserving the Host Header in the Microsoft Windows deployment documentation.

7 Runtime Status Codes

The Mendix runtime returns status codes for OData payloads. The possible status codes are the following: