Published OData/GraphQL Services

Last modified: September 10, 2024

Introduction

In Studio Pro, entities and microflows by adding them to a published OData/GraphQL service. You can publish any number of related entities and microflows.

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 standard used for OData in Mendix is OData v4, which returns data in JSON format.

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

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

If you want the published service to be a GraphQL service as well, you can indicate that it supports GraphQL. Please fill out this survey to provide feedback about published GraphQL services.

General

To create a Published OData/GraphQL Service, right-click on the module in your app and choose Add other > Published OData/GraphQL service. You can also edit an existing published OData/GraphQL service by double-clicking on it, or right-clicking on it and selecting Open.

Service Name

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

Version

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

Location

The location denotes where the service will be available. It is recommended to include the service name and the major version in the location (for example, svc/products/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.

Supports GraphQL

Default: No

Choose Yes to publish the entities in a GraphQL service. This allows clients to send GraphQL POST requests to the location of the service. The service responds with the requested entity data in JSON format. This option is available when the GraphQL feature is enabled or when the value is Yes.

See Supported GraphQL Operations for an overview of the operations of the resulting GraphQL service.

Not all features that you can model in a published OData/GraphQL service are supported through GraphQL. See GraphQL Limitations for more details.

Entities

This list gives an overview of all published entities.

Entity Details

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

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.

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.

Microflows

This list gives an overview of all microflows published as OData actions.

Parameters

This list gives an overview of the parameters of a selected microflow.

Settings

Configuration

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.

Namespace

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

Associations

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

Include Metadata in Response by Default

This checkbox allows you to choose if the service should include the metadata (for example, the @context property) in the response. This setting is enabled by default to conform to the OData specification. Disabling this setting has the same effect as including metadata=none in the Accept header of your HTTP request. Note that the value passed in the Accept header always takes precedence over this setting.

Export

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

Service feed

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

Metadata

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

OpenAPI

The OpenAPI JSON file contains the service’s REST contract in OpenAPI 3.0 format. This is a machine-readable file according to the OpenAPI Specification format. Most API tools support this format.

When the app is running, you can also download this file from the API documentation page, under /odata-doc/{location}/openapi.json, where {location} is the location of the OData service (for instance, odata/myservice/v1)).

GraphQL Schema

The GraphQL schema describes the queries and types exposed by this GraphQL service. You can export the GraphQL schema when this service supports GraphQL.

Security

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

Requires Authentication

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

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

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 published entity)

Check more than one authentication method to have the service try each of them. It will first try Custom authentication, then Username and password, then Active session.

Username and Password

Authentication can be done by including basic authentication in the HTTP header of the call. To do this, 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==.

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:

var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", "http://mysite/odata/myservice/myentity", false);
xmlHttp.setRequestHeader("X-Csrf-Token", mx.session.getConfig("csrftoken"));
xmlHttp.send(null);
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)
Mendix SSO

You can configure a published OData/GraphQL 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 the Mendix SSO module has been installed and configured in your app.
  2. In the published OData/GraphQL service, choose Custom authentication and select the AuthorizeRequestWithAccessTokenFrom Request microflow.

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.

Public Documentation

In the Public documentation tab, you can write a summary and a description intended for people using the service. This documentation is used in the service’s OpenAPI documentation.

OpenAPI Documentation

In the OpenAPI Documentation pane, you can see a preview of the API documentation for the published OData service. It lists the available operations and schemas that will become available when you run the app. This is similar to the Swagger UI page that is available after publishing your app, with the exception that the preview is not interactive.

Properties

In the Properties pane when an OData/GraphQL 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.

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.

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, the illegal characters are replaced by the DEL character, and the client will not get an error. However, the data the client receives will not be exactly what is stored in your database because these characters have been replaced.

The 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

Runtime Considerations

API Documentation

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 Supported OData Operations.

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

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

On-Premises Deployments

Some on-premises servers (in particular, those using Microsoft IIS) will strip the host header from requests. This means 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.

Runtime Status Codes

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

Responses to GraphQL requests return 200 when the server understands the request and can return at least some data, and 400 when the server does not understand the request.

Publishing CRUD

To publish an entity with full CRUD (Create, Read, Update, or Delete functionality; or in Studio Pro, Insertable, Readable, Updateable, and Deletable), select the relevant checkboxes in the Capabilities section in Published OData Entity. You can then Send and Delete objects using External Object activities.

Limitations

OData Limitations

Studio Pro currently does not support publishing media entities with OData services. To learn about consuming media entities with OData, see the Binary Attributes section of Consumed OData Service Requirements. You can also Publish and Retrieve Images and Files with REST.

GraphQL Limitations

A service that supports GraphQL does not support all of the modeling features available for OData services. See Supported GraphQL Operations for an overview of what clients can retrieve when you publish an entity.

The following modeling options are limited in the GraphQL service:

  • Published microflows are ignored.
  • The insertable, updatable, and deletable capabilities values have no effect, because GraphQL services are read-only.
  • Entities that are not readable are not part of the GraphQL service.
  • Entities without a key are not part of the GraphQL service.
  • The Use paging setting has no effect.
  • Published ID attributes are ignored.
  • Published owner and changedBy system associations are ignored.
  • Enumerations exposed as a string are ignored.
  • Binary attributes are ignored.
  • A published OData service that publishes associations as an associated object ID cannot support GraphQL.
  • The GraphQL endpoint is not part of the OpenAPI document.