Published OData Entity

1 Introduction

This document describes the properties of an entity published in an OData service.

For an overview of OData services, see Published OData Services.

2 Adding or Editing an Entity

2.1 Add an Entity

In the Entities pane of the Published OData Service window, click Add to open the Select Entity window. Select an entity to publish and click Select.

An alternative way to add an entity is by right-clicking an entity in the domain model and choosing Publish in OData service. You can select a published OData service or create a new one.

2.2 Edit a Published Entity

In the Entities pane of the Published OData Service window, select an entity and click Edit to display the Edit published entity window.

It is possible to select another entity or view the entity in the domain model by clicking Show.

You can see the location where the entity is published in Example of location.

In the Public documentation tab, you can provide a summary and a description of the published entity.

3 Selecting Published Attributes and Associations

When you have selected an entity in the list to the left, its published attributes and associations are shown in the list to the right. In this list, you can add, edit, delete, and move these attributes and associations.

Attributes of published entities are Nillable by default. This means if their value is empty, they will be encoded as explicit nulls in the OData content. If Nillable is unchecked for an attribute, the attribute cannot be empty (as this will result in a runtime error).

You cannot include associations to and from entities that are published without the Readable capability.

3.1 Required Validation Rules for Published Attributes

For published OData services, the Can be empty checkbox appears when you edit a published attribute.

When the checkbox is unselected and there is no Required validation rule set, you are prompted to add a required validation rule or use a before commit microflow to ensure end-users do not leave it empty.

4 Mapping from Internal Names to Exposed Names

Use Exposed entity name in the Edit published entity window to customize the name of the entity that is exposed to the outside world. The default is the name of the published entity in the domain model. The Exposed entity name must start with a letter followed by letters or digits with a maximum length of 480 characters.

Attributes and associations can be customized in the same way by clicking Edit in the list on the right.

For associations, the exposed name is the name given to the navigation property, which is the property referring to the associated object (or objects). The default is the same as the name of the association in the domain model.

These features make it easier to refactor the domain model without affecting external APIs.

5 Key

Every entity in Mendix has an ID that is used internally to store the object in the database. However, this ID is not stable over time, as it can change in certain scenarios (such as data migration). That means it is not recommended to use the ID as a key. A published entity should have a key attribute or a combination of attributes that form a key instead. The attribute (or attributes) can be of type Integer, Long, String, or AutoNumber.

Select a combination of attributes with the following constraints:

• Unique – The combination of key attributes should be unique so each key points to exactly one object.
• Required – If one of the key attribute values is empty, you cannot find an object with it anymore.
• Stable over time – The attribute values used for the key should not change so you can find it again later.

Having an index for the key attribute (or attributes) makes retrieving objects by key perform better.

You can set unique and required constraints using validation rules.

Selecting a key is required when the Readable capability is enabled.

6 Capabilities

The Capabilities section gives an overview of what operations the published entity supports.

6.1 Insertable

Select the checkbox for Insertable to indicate that clients can insert new objects.

When the app receives a request to insert a new object, it does the following:

1. It checks that the request is formatted correctly, rejecting things like specifying a string value for an integer attribute.
2. It checks that the requested changes are valid, rejecting things like strings that are longer than the maximum length and empty values for required attributes.
3. It creates a new object with the values specified in the request.
4. It commits the object to the database.

This is the behavior when you choose the action Write to database.

You can also choose the Call a microflow action to use your own logic. Specify a microflow that takes the entity as a parameter, and optionally a System.HttpRequest parameter. In the microflow, you can use the Commit activity to commit the changes to the database.

In the publishing app, you can use a validation message action to report a validation error. The client app can include a custom error handler on the Send External Object activity to handle the error. If the microflow reports validation feedback, the runtime informs the client that the request has failed. For more information, see Supported OData Operations.

6.2 Readable

There are two options to handle an incoming GET request for a published entity:

1. Read from database – This action will parse the incoming OData query to a database query and retrieve the data from the database. This is the default action for Readable section. This action is not applicable to non-persistable entities, because non-persistable entities cannot be retrieved from the database.
2. Call a microflow – This action will call a microflow. You can specify your custom logic in this microflow to return a list of objects that correspond to the incoming request.

You can also set the query options for each request.

A published OData entity is readable by default. It is possible to disable this capability, which means the service only exposes the type and structure of the entity, not the data. You can use the entity as a parameter or return type of a published microflow.

When Readable is enabled, you can configure how data is queried in the exposed data section. Note that Readable must be enabled in order to enable the other capabilities.

6.2.1 Query Options

Select the options to include for the Readable OData capability:

• Countable – This option is required for getting the total number of records.
• Top supported – This option indicates whether clients can specify that they want to retrieve only a limited number of items. Enable this option when Use paging is selected.
• Skip supported – This option indicates whether clients can specify the number of items in the queried collection that are to be skipped and not included in the result. Enable this option when Use paging is selected.

The Top supported and Skip supported queries are required for pagination, which is when the server allows the client to request only a subset of the data and skips the first n objects. Paging occurs when the client requests a lot of data and the server returns a subset and a link to request the rest.

For more information, see the System Query Option $top and $skip in the Basic Tutorial on OData.org

6.3 Updatable

Select the checkbox for Updatable to indicate that clients can update the values of attributes and associations.

When the app receives a request to change values, it does the following:

1. It checks that the request is formatted correctly, rejecting things like specifying a string value for an integer attribute.
2. It checks that the requested changes are valid, rejecting things like strings that are longer than the maximum length and empty values for required attributes.
3. It commits the changes to the database.

This is the behavior when you choose the action Write to database.

You can also choose the Call a microflow action to use your own logic. Specify a microflow that takes the entity as a parameter, and optionally a System.HttpRequest parameter. In the microflow, you can use the Commit activity to commit the changes to the database.

In the publishing app, you can use a validation message action to report a validation error. The client app can include a custom error handler on the Send External Object activity to handle the error. If the microflow reports validation feedback, the runtime informs the client that the request has failed. For more information, see Supported OData Operations.

6.4 Deletable

Select the checkbox for Deletable to indicate that clients can delete the values of attributes and associations.

Choose whether the object should be deleted from the database directly, or whether to call a microflow. Specify a microflow that takes the entity as a parameter, and optionally a System.HttpRequest parameter. In the microflow, you can use the Delete activity to delete the object from the database.

You can use a validation message to report a validation error if you are performing, for example, a soft delete. If the microflow reports validation feedback, the runtime informs the client that the request has failed.

7 Exposed Data

7.1 Exposed Set Name

It is possible to customize the name of the entity set that is displayed in the Exposed set name field of the Edit published entity window. This forms the last part of the URL of the published entity as given in the Example of location.

Default: {Entity name}s

7.2 Use Paging

The Use paging option is used to set a maximum number of objects per response and includes a link to the next set of objects. A client such as Tableau is able use this to display progress and automatically continues to follow the links until all the data is retrieved. The memory usage of the clients can be improved if paging is set to a reasonable page size.

Default: No

When set to Yes, select Top supported and Skip supported query options.

Setting Use paging to Yes may result in inconsistency in the retrieved data because the data will not be retrieved in a single transaction. For example, sorting on the Age attribute in an entity called Customer and retrieving customers set to 1000 objects per page. If a customer is deleted between two calls, the customer with Age 23 at position 1001 moves to position 1000. This means the object that would be the first item on the second page is moved to the first page and is no longer retrieved. Similarly, data inserted between calls can result in a duplication of the data. This option should only be used when this kind of inconsistency is acceptable.

7.3 Page Size

When Use paging is set to Yes, the number of objects per page can be set in Page size.

Default: 10000