You can expose selected MDriven Turnkey ViewModels as REST endpoints for clients that need to read or update modeled data.

How REST exposure works

A REST endpoint is enabled per ViewModel. The caller supplies the ViewModel name and a root object ID, and Turnkey loads that object into the ViewModel. Turnkey checks the ViewModel's access groups before it processes the request.

For example, a ViewModel named ArticleViewModel, rooted in Articles1, can expose article fields for the object with ID 3!396.

Create an endpoint

1. In MDriven Designer, create or open the ViewModel that represents the data you want to expose.
2. Select the ViewModel root and set its Class property to the domain class that the endpoint will operate on. For example, set ArticleViewModel to class Articles1.
3. Add the fields that the endpoint should return or accept. Use direct attribute mappings for fields that clients must update.
4. In the ViewModel Editor, select Tagged values in the top-right corner.
5. In the Tagged Values dialog, select Eco.RestAllowed in the Value Store, select Add This, and set its value to True.
6. Upload the model and run the Turnkey application.

Setting Eco.RestAllowed to True registers the ViewModel for REST. Without this tagged value, Turnkey does not make GET, POST, PUT, PATCH, or DELETE available for the ViewModel.

Choose fields deliberately

The REST response contains the ViewModel content as JSON. Create a dedicated REST ViewModel when the UI ViewModel contains fields, actions, or navigation that an API client should not receive.

For example, expose these direct mappings when a client must patch article data:

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

A computed OCL expression returns its computed display value. For example, 'By ' + self.author returns By Ada, not the stored author value Ada. Do not use computed expressions for fields that need predictable PATCH behavior.

Call the endpoint

Use either the legacy TurnkeyRest route or the /Rest/ route.

HTTP verb	Route	Example
GET	TurnkeyRest/Get?command=vmname&id=rootobjref	https://host/Rest/ArticleViewModel/Get/3!396
POST	TurnkeyRest/Post?command=vmname&id=rootobjref	https://host/Rest/ArticleViewModel/Post/3!396
PUT	TurnkeyRest/Put?command=vmname&id=rootobjref	https://host/Rest/ArticleViewModel/Put/3!396
PATCH	TurnkeyRest/Patch?command=vmname&id=rootobjref	https://host/Rest/ArticleViewModel/Patch/3!396
DELETE	TurnkeyRest/Delete?command=vmname&id=rootobjref	https://host/Rest/ArticleViewModel/Delete/3!396

Use a complete object ID, such as a GUID or xx|yyyy. Do not use an ID shortcut without its class identifier; it can resolve incorrectly.

The shorter PATCH route also works:

https://host/Rest/ArticleViewModel/Patch?id=3!396

Send parameters and data

Declare String ViewModel variables for request parameters. Turnkey assigns matching query-string or form values to those variables.

For example, declare vRegion:String and call:

https://host/Rest/ArticleViewModel/Get/3!396?vRegion=Europe

For GET, parameter names are matched to ViewModel variables. Use root-level actions to retrieve additional information.

For POST, parameter names are matched to ViewModel variables and attributes. Root-level actions then run in their ViewModel order, and POST saves changed values to the database.

If a client sends JSON that must create or populate modeled objects, process the JSON in an action with selfVM.JSonToObjects:

selfVM.JSonToObjects( «Type» , JSonDataInStringFormat)

JSonToObjects matches JSON names to attributes and associations and can create an object tree.

Receive raw request content

Turnkey treats posted form fields as values for matching ViewModel columns. To receive a non-form string body, add a column named exactly STRINGCONTENT. To receive a non-form binary body, add a blob column named exactly BYTEARRAYCONTENT.

To inspect incoming request headers, add a variable named vRequestHeaders. Turnkey fills it with a JSON string. For example, read the Host header with:

vRequestHeaders.JsonGetProp('Host')

Control behavior by HTTP verb

Add a String variable named vRestVerb to learn which HTTP verb called the ViewModel. You can use it in an action guard or a OCL expression.

For example, make an action read-only except for PUT:

vRestVerb<>'Put'

PATCH existing objects

RestPatch maps to HTTP PATCH. It updates only the fields included in the request; all other fields remain unchanged.

For example, PATCH title=Updated Title to:

https://host/Rest/ArticleViewModel/Patch/3!396

A successful PATCH returns 200 OK and the full updated ViewModel as JSON. If the ViewModel field is computed, the response contains the computed value even though the underlying attribute was updated.

Customize the response

GET and POST return the ViewModel as JSON by default. You can replace that response in either of these ways:

• Add a String attribute named exactly RawJSon to the root object. Its value is returned instead of the ViewModel JSON.
• Add the ViewModel variables vReturnMessage:String and vReturnStatusCode:String. vReturnMessage becomes the response content and vReturnStatusCode sets the HTTP status.

For example, an action can return a not-found response:

vReturnStatusCode:='NotFound'
vReturnMessage:='Article not found'

The status code must be a value from .NET System.Net.HttpStatusCode, such as Created or NotFound. If the status code is not valid, Turnkey returns 200 OK.

If processing fails, Turnkey returns error: <message>.

Access and debugging

REST exposure does not bypass access control. After Turnkey finds the ViewModel and root object, it checks the ViewModel access groups. Configure access before you expose data that is not intended for anonymous callers.

Use an HTTP client such as Postman to test the route, object ID, headers, parameters, and request body. When diagnosing an outgoing request, postman-echo.com can show what the request contains.

See also

• HowTos:Expose REST Service
• Documentation:OCLOperators RestPatch
• Documentation:Rest API
• Documentation:Rest Delete