Training:Rest Services In MDriven

REST services are services that are executed by connecting to an URL that defines operation and parameters then it returns an answer – not seldom as JSon objects.

You must set the tagged value RestAllowed on ViewModels you want to allow Rest access to.

Calling existing REST services

MDriven supports a couple of EAL operators to manage REST services. All operators reside on the selfVM variable – available only in the ViewModel context.

selfVM.RestGet(targeturl,user,pwd,optionalnestingwithheaders)

Read: OCLOperators RestGet

selfVM.RestPost(targeturl,user,pwd,optionalnestingwithheadersAndUploadValues)

Read: OCLOperators RestPost

selfVM.RestDownload(targeturl,user,pwd,optionalnestingwithheaders)

Read: OCLOperators RestDownload

Note! optionalnestingwithheaders is the name of the blue view model class in the example below (as a OCL String).

Example

The action GetExporttest retrieves data by converting another viewmodel to xml - it stores it in the variable vText

Next action invokes RestPost to send that data to an url-address, it also says that it should look at the nesting named 'Xml' - in this nesting we have the STRINGCONTENT (see also OCLOperators RestPost) which get's it's content from the vText variable - we also add the header Authorization with a bearer token in order to get access from the receiving service.

Exposing ourselves as a REST service

And when it comes to exposing ourselves to others – Turnkey has two MVC verbs, Get and Post, like this;

TurnkeyRest/Get?command=vmname&id=rootobjref

TurnkeyRest/Post?command=vmname&id=rootobjref

See Improved routes for another URLs.

The ViewModel name is supplied as the command parameter.

The id parameter is an object reference in one of several available formats. Read more here about how to create these.

Caution: Always send a complete id, i.e. a guid or xx|yyyy. Using a shortcut without class identifier can cause problems.

Note that the variables set in your viewmodel has to be of the String type.

The commands does this;

We check that the tagged value RestAllowed has been set on the viewmodel, then we look up the root object.

When the viewmodel and it's root has been found and the accessgroups are checked to see if access is allowed.

Then additional parameters are set (these can be either URL Encoded or multi-part form encoded. See HTTP POST for details).

• For Get, the parameter names are looked up against ViewModel variables and variable values are set.
• For Post, the parameter names are looked up against ViewModel variables and attributes and values are set.

Then any actions present at the root level of the ViewModel are executed, in the order presented in the viewmodel from top to bottom.

• For Get, use the actions to look up additional information.
• For Post, the actions are usually used to process sent JSON data into objects (see below)

Post saves any changed values to the database.

Both Get and Post returns the viewmodel content as JSON in the HTTP response. To override this use 1 one these strategies:

1. add a string attribute named exactly RawJSon on the root - if found this is returned instead of the complete vm as json.
2. add a vReturnMessage:String variable as described further down on this page

If there is an error – a string “error: <message>” is returned.

If you need to receive post data not known at design time please read Receive post data not known at design time.

You may use c# code to post to TurnkeyRest.

Processing JSON into objects

If you want to send data as JSON in a POST you need to apply the JSON string to your systems modelled objects.

Use Tajson or the simpler JsonToObjects. Read more here on XML or JSON support: Import xml and JSon with MDriven

The selfVM.JSonToObjects creates objects with the root in a of class and matches attributes and association from the JSON data – and it can create object trees (unclosed graphs) by following names on associations.

selfVM.JSonToObjects( «<Type>» ,  JSonDataInStringFormat)

You can use an existing JSON as a template to create a model section that you can import into, see Using JSON or XML as class template.

Video

To make your experience more comfortable, we set the main tags mentioned in the video to the right bar menu of this mini player. Choose the interesting subtitle on the list and immediately get to the exact theme navigation-itemplace in the video. Now you can pick any topic to be instructed without watching the whole video.

What is REST? How does it work with MDriven turnkey? calling an existing REST service exposing ourself as REST service MDriven turnkey app slot how to expose information as the Rest service? MDriven Rest/get strategy how to consume data? selfvm Rest/Get operator hard-coded objects Json to objects operator update data with allow post RestPost operator as a post command operation execution vSomeParam adding new parameters

Return Status codes, and override returned data

New from 2020-12-09 you can now override return result data and code by declaring variables in your RestAllowed ViewModel:

vReturnMessage:String
vReturnStatusCode:String

The vReturnMessage (reason code) must be found and will be returned as content instead of the default (to make json of the viewmodel) - the return message will have the status code of vReturnStatusCode

If the vReturnStatusCode is found it must have one of the values defined here: https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=net-5.0 otherwise 200 "Ok" is returned

Read status code from RestPost, RestGet etc

Use the vReturnStatusCode:string variable name to get Status from quering others with rest - RestPost, RestGet etc.

Use the vReturnMessage:string variable name to get the reasoncode from other with rest.

Receive string content

We assume postback data as FormFields that we match to ViewModelColumns. If someone posts string content (no form data) we now put that data in column named "STRINGCONTENT" if found.