Documentation:REST services and operators

REST services and operators

This page was created by Wikiadmin on 2026-07-29. Last edited by Wikiadmin on 2026-07-29.

You can expose selected MDriven Turnkey ViewModels as REST endpoints and call external REST services from ViewModel OCL expressions.

REST in MDriven

REST (Representational State Transfer) is an HTTP-based integration style. In MDriven, you use it in two directions:

Need	Use	Example
Expose data or operations from your application	Enable REST for a ViewModel with `Eco.RestAllowed`.	Expose an `Item` ViewModel that returns an item's name, image URL, and image width as JSON.
Call an external service	Use REST operators on `selfVM` in a ViewModel.	Call an external URL with `RestGet` and store the returned text in a ViewModel variable.

A REST response is defined by the ViewModel, not directly by the model. The columns and nestings that you place in the ViewModel determine the data returned. For example, a column named pictures can use an expression that navigates the model association named images. The external JSON field is then pictures, while the model association remains images.

Expose a ViewModel as a REST endpoint

Use this approach when another system needs to retrieve or modify data through a ViewModel.

In MDriven Designer, open the ViewModel that defines the data you want to expose.
Select the ViewModel head.
Set the Rest allowed property to true. This corresponds to the Eco.RestAllowed tagged value described in Documentation:Span.Eco.RestAllowed.
Add the columns and nestings that the client should receive. Use OCL expressions to control both values and field names.
Remove actions and presentation-only content that are not part of the REST contract. If the ViewModel is only for REST, turn off presentation hints so that rendering details do not obscure the endpoint definition.
Upload or deploy the changed model to your Turnkey application.

For example, a rooted RestExposedItem ViewModel can expose these values:

ViewModel field	Example expression	Purpose
`name`	`self.name`	Returns the item name.
`pictures`	A nesting based on `self.images`	Returns related images under the externally chosen name `pictures`.
`url`	`self.url`	Returns an image URL.
`width`	`self.width`	Returns the image width.

A rooted ViewModel request must identify both the ViewModel and the root object. REST requests use the REST route and an HTTP verb such as GET, POST, PUT, PATCH, or DELETE. Verify the generated endpoint URL for your deployed application and ViewModel. The REST walkthrough shows an MDrivenRest/get request containing the ViewModel name and root object identity; newer endpoint examples use a /Rest/<ViewModelName>/ route.

Do not enable Rest allowed on every ViewModel. It makes that ViewModel available as a REST data source. Protect endpoints that return non-public data with authentication and access rules.

= POST action order

For REST POST, action placement in the root ViewModel class controls when an action runs:

Actions before all root attributes run before incoming values are applied.
Actions after the root attributes run after incoming values are applied.

For example, place an early action before attributes when it must locate an object from a URL-coded value. Place a later action after attributes when it must process the submitted values. See Documentation:Rest Post.

Call an external REST service

REST operators are available on the selfVM variable and only in ViewModels. The available operators are RestPost, RestGet, RestPut, RestDelete, and RestDownload. Use them to retrieve data, submit data, delete remote data, or download returned files.

For example, an action can call an external endpoint and assign its response to a string ViewModel variable:

result := selfVM.RestGet('https://service.example/api/item', '', '', '')

The RestGet operator accepts a target URL, user name, password, and nesting name. In the example, the user name, password, and nesting name are empty. Store the returned value in a ViewModel variable when you need to display it or process it in later expressions.

Use a ViewModel nesting to supply data and headers for requests that send content. REST POST and PUT can send content; GET does not send ordinary request content.

Request content and headers

For REST POST and PUT, special nesting-column names control the outgoing content and headers. See Documentation:OCLOperators RestPost for the complete operator rules.

Nesting column name	Effect	Example
`STRINGCONTENT`	Sends the value as `StringContent`. Use it as the single content column, apart from header columns.	Send a JSON document held in one string.
`BYTEARRAYCONTENT`	Sends the value as `ByteArrayContent`. Use it as the single content column, apart from header columns.	Send a binary document.
`FILENAME_xxx`	Sets the filename for a multipart field named `xxx`.	`FILENAME_document` supplies the name for the `document` byte array.
`CONTENTTYPE_xxx`	Sets the content type for a multipart byte-array field named `xxx`.	`CONTENTTYPE_document` can be `application/pdf`.
`HEADER_xxx`	Adds a content header named `xxx`.	`HEADER_Authorization` adds an Authorization content header.
`HEADERMINUS_xxx`	Adds a content header after converting underscores to dashes.	`HEADERMINUS_Content_Type` becomes `Content-Type`.
`DEFAULTREQUESTHEADER_xxx`	Adds a request header.	`DEFAULTREQUESTHEADER_Accept` adds an Accept request header.
`DEFAULTREQUESTHEADERMINUS_xxx`	Adds a request header after converting underscores to dashes.	`DEFAULTREQUESTHEADERMINUS_X_Request_Id` becomes `X-Request-Id`.

The default POST and PUT content is multipart form data. Set HEADERMINUS_Content_Type to application/x-www-form-urlencoded when the receiving service requires URL-encoded form data; the other columns are then sent as string name/value pairs.

Avoid FORCEREQUESTCONTENTTYPE unless the receiving framework requires a Content-Type header on GET. GET with content is not a valid normal request; this option works by adding empty content with a header.

Security

Treat an exposed ViewModel as an external contract. Return only the fields that a caller needs, and do not assume that hiding a field in a normal UI protects it from an enabled REST ViewModel.

Use authentication for endpoints that are not public. One supported pattern is basic authentication with a dedicated user and a strong password. You can also apply more advanced token-based authentication and access control. Test each endpoint without credentials and with the intended credentials before publishing its URL.

Contents