In Studio Pro, entities can be exposed as OData resources by adding a new 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.
The standards used for OData in Mendix are:
- OData version 3, which returns data in Atom XML format.
- OData version 4, which returns data in JSON format.
The OData version 4 feature was introduced in Studio Pro 9.4.0.
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.1 Service Name
Use the version field to assign a version number to the service. This number will be shown in the API documentation.
It is recommended that you adopt semantic numbering for services that you publish.
In OData, the namespace is used to refer to data types. On the Settings tab, you can customize this namespace. You can change it to any value which starts with a letter followed by letters, digits, or dots with a maximum length of 512 characters.
A resource is a network-accessible data object represented by an entity and identified by a URI.
3.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.
This setting was introduced in Studio Pro 9.4.0. In earlier versions, all published OData services were OData 3.
You can select how you want to represent associations. For more information, see the Associations section of OData Representation.
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. Choose No to allow access to the resources without restrictions. Choose 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, refer to 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 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.
22.214.171.124 Username & 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:
- Username and password are combined into a string “username:password”.
- The resulting string is then encoded using the RFC2045-MIME variant of Base64 (except not limited to 76 char/line).
- 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==.
126.96.36.199 Active 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/myresource", false); xmlHttp.setRequestHeader("X-Csrf-Token", mx.session.getConfig("csrftoken")); xmlHttp.send(null);
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.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.
Web service users cannot access OData services.
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.
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.
4.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
4.3 Public Documentation
You can write a summary and a description intended for people using the service.
5 Runtime Considerations
Once your app is published, the published OData services will be is available on the root URL of the app followed by
/odata-doc/. For example,
http://localhost:8080/odata-doc/ You can copy and paste the links into for instance Excel to establish a link between your OData resources and Excel.
While the API documentation for OData resources is enabled by default, access to it may be restricted by the administrator for apps running in production.
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.
5.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.