You can expose a ViewModel from MDriven as a REST endpoint for other systems, or use MDriven to call REST services provided by another system.

Choose the REST direction

REST is an HTTP-based way for systems to exchange resources and operations. In MDriven, distinguish these two directions before you start:

Goal	What you configure	Example
Expose MDriven data or actions	A ViewModel that is allowed to serve REST requests	An external application reads or updates an Article through an MDriven endpoint.
Consume an external REST service	A ViewModel action that calls the external service	A payment workflow requests a token, submits a payment request, and later queries its status.

Expose a ViewModel as a REST endpoint

A ViewModel is the contract that controls which data and actions a caller can use. Do not expose a domain class directly; create a ViewModel with only the fields and actions that the integration requires.

Enable REST access

To make a ViewModel available through REST:

1. Open the ViewModel in MDriven Designer.
2. Add the attributes and actions that the endpoint must expose.
3. Open Tagged values in the upper-right area of the ViewModel Editor.
4. Add the Eco.RestAllowed tagged value and set it to True.
5. Run the application and call the ViewModel endpoint.

Eco.RestAllowed is required. The default value is False; without this setting, REST operations are not available for the ViewModel. RestAllowed and UIAllowed describes the separate REST and user-interface access settings.

Use the endpoint URL

The REST URL uses the ViewModel name:

http://<host>/Rest/<ViewModelName>/

For a ViewModel named ViewOneThing, MDriven supports the following GET URL forms for an object identified by 11!1:

http://localhost:5052/TurnkeyRest/Get?command=ViewOneThing&id=11!1
http://localhost:5052/Rest/ViewOneThing/Get?id=11!1
http://localhost:5052/Rest/ViewOneThing/Get/11!1

The value 11!1 is an MDriven object ID. Use the ViewModel name exactly as it is defined in the model.

Design fields for predictable responses

Add direct mappings when callers need the stored value. For example, a ViewModel rooted to an Articles1 class can expose:

title       : self.title
publishedAt : self.publishedAt
content     : self.content
author      : self.author

A field may instead use an OCL expression to produce a display value:

author : 'By ' + self.author

The REST response returns the computed display value for such a field. This matters when updating data: use direct mappings, such as self.title, for fields that clients must patch cleanly.

Select the HTTP operation

The HTTP method determines what the caller requests. Keep each operation focused on its own purpose.

HTTP method	Typical purpose	MDriven guidance
GET	Read a resource	Use the REST ViewModel URL and object ID where required.
POST	Submit data or create a resource	REST POST also explains the order in which root ViewModel actions run relative to incoming values.
PUT	Update or create the resource identified by the URL	See REST PUT.
PATCH	Update only selected fields on an existing object	See RestPatch.
DELETE	Delete the resource identified by the URL	See REST DELETE.
HEAD	Retrieve response headers without the response body	Use RestHead when you need to check availability, status, or metadata without downloading the resource body.

Update selected fields with PATCH

Use PATCH when a caller must change only part of an object. With Eco.RestAllowed enabled, the endpoint format is:

http://<host>/Rest/<ViewModelName>/Patch?id=<objectId>

For example:

http://localhost:8182/Rest/ArticleViewModel/Patch?id=3!396

Send only the fields to update as key-value pairs in the request body. If the request contains title=Updated Title, the title is updated and fields not included in the request remain unchanged. A successful PATCH returns 200 OK and the complete updated ViewModel object as JSON. See RestPatch for the full setup and request details.

Control POST action order

A REST POST can execute actions in the root ViewModel class. Actions placed before root attributes run before incoming values are applied; other root actions run after the values have been applied.

For example, place an action that looks up context from URL-coded variables before the attributes. Place an action that validates or processes the submitted values after the attributes. See REST POST for details.

Consume an external REST service

When MDriven calls a service owned by another system, keep the external service contract separate from your ViewModel contract. Define the external URL, method, required headers, authentication flow, request body, and expected response according to that provider's API documentation. Use a ViewModel action to coordinate the workflow; RestHead is one available REST operator for HEAD requests.

A payment-service workflow commonly has these stages:

1. Request or obtain an access token from the provider's authentication endpoint.
2. Send the business request, such as a request-to-pay operation, with the required headers and body.
3. Store the provider's reference identifier returned or submitted for that request.
4. Query the transaction-status endpoint using that reference identifier.
5. Handle an expired access token by obtaining a new token before retrying the provider operation.

For example, a provider may require a subscription key as well as OAuth 2.0 credentials. Treat both as provider-specific requirements: do not assume that another REST service uses the same headers, token lifetime, or key-management process.

Header names with hyphens

Some external APIs require header names containing hyphens. In the Mobile Money example, Ocp-Apim-Subscription-Key is represented as HEADERMINUS_Ocp_Apim_Subscription_Key: use the HEADERMINUS_ prefix and replace hyphens with underscores in that header parameter name. Apply this transformation only where the MDriven REST-call configuration expects that form.

Test each provider operation separately

Test authentication, the business request, status inquiry, balance inquiry, and user-information inquiry independently. Record the request reference from the business request and use it in the subsequent status call. If a provider endpoint is unavailable, verify the provider service and credentials before diagnosing the MDriven model.

Keep REST contracts intentional

• Expose only fields and actions that an external caller needs.
• Use direct ViewModel mappings for values that clients update.
• Set Eco.RestAllowed only on ViewModels intended for REST access.
• Treat external authentication headers, credentials, and token expiry as part of the external provider contract.
• Test every HTTP operation with the exact URL, object ID, headers, and body required by its contract.

See also

• Documentation:RestAllowed UIAllowed
• Documentation:Rest Post
• Documentation:OCLOperators RestPatch
• Documentation:Rest Delete
• Documentation:Api documentation
• Documentation:REST API For MDriven Versioned Downloads

Expose MDriven data as a REST endpoint

MDriven supports both exposing services through REST and consuming REST services from other systems. The Mobile Money example on this page is an example of the latter: MDriven consumes an external API.

To expose MDriven data, create a ViewModel for the domain class you want to make available and set Eco.RestAllowed to True. This registers the ViewModel as a REST endpoint.

Set up a REST-allowed ViewModel

1. Create a ViewModel rooted at the domain class that contains the data to expose. For example, ArticleViewModel can be rooted at Articles1.
2. Add the fields that should be available through the ViewModel. For example:

   title       : self.title
   publishedAt : self.publishedAt
   content     : self.content
   

3. In the ViewModel Editor, open Tagged values and add Eco.RestAllowed with the value True.
4. Run the application. The ViewModel endpoint is available at http://<host>/Rest/<ViewModelName>/.

For example:

http://localhost:8182/Rest/ArticleViewModel/

Without Eco.RestAllowed, REST operations are not available on the ViewModel.

Response behavior

GET and POST return the ViewModel content as JSON by default. POST saves changed values to the database.

The response reflects the fields and expressions defined by the ViewModel. If a field uses a computed expression, such as 'By ' + self.author, the response contains the computed value rather than the raw stored value.

You can override the default response by adding variables to a REST-allowed ViewModel:

Variable	Result
RawJSon string attribute on the root	Returns its value instead of the complete ViewModel JSON.
vReturnMessage:String	Returns the message instead of the default ViewModel JSON.
vReturnStatusCode:String	Sets the HTTP status code when it contains a valid HTTP status-code value, such as NotFound or Created.

Update selected fields with PATCH

Use PATCH to update fields on an existing object while leaving fields omitted from the request unchanged.

http://<host>/Rest/<ViewModelName>/Patch?id=<objectId>

For example:

http://localhost:8182/Rest/ArticleViewModel/Patch?id=3!396

The object ID contains the MDriven class ID and instance ID. Send the fields to update as key-value pairs in the request body. A request containing title=Updated Title updates the title while leaving other omitted fields unchanged.

On success, PATCH returns 200 OK and the full updated ViewModel object as JSON. For predictable PATCH behavior, use direct field mappings such as self.title rather than computed expressions.

See Expose REST Service for REST response handling and RestPatch for PATCH setup and examples.

REST integration direction

Goal	Documented approach
Make MDriven ViewModel data available through REST	Create a ViewModel and set Eco.RestAllowed to True.
Call a REST API owned by another system	Use MDriven REST-service consumption functionality. The Mobile Money example on this page demonstrates this direction.

Expose a ViewModel as a REST endpoint

MDriven can expose a ViewModel as a REST endpoint. Create a ViewModel for the data you want to make available, then enable REST access for that ViewModel.

Create the endpoint

1. Define or select the domain class that represents the data to expose.
2. In the ViewModel Editor, create a ViewModel and set its Class property to that domain class. This roots the ViewModel in the selected class.
3. Add the fields to expose as ViewModel columns. For example:

title       : self.title
publishedAt : self.publishedAt
content     : self.content
author      : self.author

1. In the ViewModel Editor, open Tagged values.
2. Add the Eco.RestAllowed tag and set it to True.
3. Run the application. The endpoint format is:

http://<host>/Rest/<ViewModelName>/

For example:

http://localhost:8182/Rest/ArticleViewModel/

Setting Eco.RestAllowed to True registers the ViewModel as a REST endpoint. Without this setting, REST operations are not available on that ViewModel.

Read and save ViewModel data

GET and POST return the ViewModel content as JSON. POST saves changed values to the database.

The default JSON response can be replaced by adding a string attribute named exactly RawJSon on the ViewModel root.

Update selected fields with PATCH

Use PATCH to update fields on an existing object. PATCH is available when Eco.RestAllowed is set to True.

The URL format is:

http://<host>/Rest/<ViewModelName>/Patch?id=<objectId>

For example:

PATCH http://localhost:8182/Rest/ArticleViewModel/Patch?id=3!396

The object ID consists of the MDriven class ID and instance ID. The object ID may also be supplied as the final URL segment:

PATCH http://localhost:8182/Rest/ArticleViewModel/Patch/3!396

Send the fields to update as key-value pairs in the request body. Fields not included in the request remain unchanged. For example:

title=Updated Title

A successful PATCH returns 200 OK and the full updated ViewModel object as JSON.

Requirement	ViewModel guidance
Return or update a stored value	Use a direct mapping, for example title : self.title.
Return a computed display value	Use a computed expression, for example author : 'By ' + self.author. The REST response returns the computed value rather than the raw stored value.

See also

• Expose REST Service
• RestPatch