In the Modeler, 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 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.
2 OData Version
The standard used for OData in Mendix is OData version 3) with the default representation set to Atom XML. Not all parts of the standard are implemented. If something is not documented here, it is has not yet been added.
3 Query Options
For details on how to filter the OData response, refer to OData Query Options.
4 Supported Types
For details on how Mendix attributes are represented in OData, refer to OData Representation.
5 Service Name
A resource is a network-accessible data object representing an entity, identified by a URI. You can add, edit, or remove resources and their unique identifiers from the Resources tab.
7 Service Namespace
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.
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.
You can choose how you want to represent associations. For more information, see the Associations section of OData Representation.
To be able to consume OData in Mendix, you need to have two types of access rights: access right to the OData service as well as the right to the specific entities you are retrieving. Access can be granted either via authenticating as a user or via an anonymous user as long as the associated user role has access to both the OData service and the entities.
10.1 Authenticated Access
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==.
10.2 Anonymous Access
With project security enabled, OData resources can still be exposed to anonymous users. For detailed information on allowing anonymous users, refer to Anonymous User Role.
10.3 Project Security Off
If project security is off, for debugging purposes you can retrieve all data without needing to authenticate and without any security being applied. This is not possible in a production environment.
10.4 Role-Based Access
If security is enabled, it is required to configure which users have access rights to a specific OData service document. This can be done by opening the specific Published OData service document, navigating to the Settings tab and changing the allowed roles in the Security section. By default, no allowed user roles are selected. The security settings are reflected in Module Security.
10.5 How Security Works
- Typically, the client issues an initial anonymous request. The anonymous request is then validated against the OData service. If anonymous access is not granted to the respective OData service, the server will return with error code 401 (Unauthorized) and the response will include the WWW-Authenticate header to instruct the client to authenticate with basic authentication.
- If the client fails to provide correct credentials or does not provide a basic authentication at all, the server returns error code 401 (Unauthorized) and the WWW-Authenticate header, just as in the previous step.
- If the client is granted access (either anonymously or through basic authentication), the client access rights will be checked against the security configuration of the OData resources. All accessible resources are described in the Metadata XML document available under the root URL of the service with
- Each time the client makes a call to an OData service, whether it is a service description, or metadata, or resource, the authentication information will be re-evaluated.
11 API Documentation
Once your OData-enabled app is running, an overview of exposed OData resources is available on the root URL 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.