You can call external REST services from a MDriven Designer ViewModel by using selfVM REST operators in an action; use this page when your MDriven application needs to retrieve data, send data, or download a file from another system.
Choose the REST direction
REST (Representational State Transfer) services are HTTP endpoints identified by a URL. An endpoint commonly returns JSON, but a service can also return other text or a downloadable file.
MDriven supports two distinct integration directions:
| Need | Use | Example |
|---|---|---|
| Call a service provided by another system | The selfVM.RestGet, selfVM.RestPost, or selfVM.RestDownload operator in a ViewModel action
|
Send an order to an external service and receive its response |
| Make data or operations in your MDriven application available to another system | Expose a ViewModel as a REST service | Allow an integration client to retrieve or update a car record |
This page describes calling external services. For the endpoint format and steps for exposing a ViewModel from MDriven Turnkey, see HowTos:Expose REST Service. Set RestAllowed only on a ViewModel that you intend to expose; it is not the setting that enables an outgoing call.
Call a REST service from a ViewModel
The REST operators belong to selfVM, the variable available in the ViewModel context. Add an action to the ViewModel and put the call in the action's OCL expression.
Select an operator
| Operator | Use it when | Parameters |
|---|---|---|
selfVM.RestGet(targeturl,user,pwd,optionalnestingwithheaders)
|
You need to retrieve a response from an endpoint. | Target URL, user, password, and an optional nesting that supplies headers. |
selfVM.RestPost(targeturl,user,pwd,optionalnestingwithheadersAndUploadValues)
|
You need to send values or content and receive a response. | Target URL, user, password, and a nesting that supplies headers and upload values. |
selfVM.RestDownload(targeturl,user,pwd,optionalnestingwithheaders)
|
The service produces a larger result, such as a file to download. | Target URL, user, password, and an optional nesting that supplies headers. |
Use the HTTP method that the remote endpoint requires. A GET request must go to its GET endpoint and a POST request must go to its POST endpoint. Sending a POST command to a GET endpoint does not apply posted data.
Create the parameter nesting
- In the ViewModel, create the blue ViewModel class (nesting) that will hold request information.
- Give the nesting a name that you will pass as the final operator argument, for example
'Xml'. - Add the values required by the remote service to this nesting.
- Add the ViewModel action that calls the selected
selfVMoperator. - Store the returned text in a ViewModel variable if you need to show it, inspect it, or use it in later actions.
The final argument is an OCL string containing the name of the nesting. For example, 'Xml' refers to a blue ViewModel class named Xml; it is not the XML content itself.
Post XML content and an authorization header
A common pattern is to build XML in one action and send it in the next action.
- Create an action that converts the source data from another ViewModel to XML and stores the result in a ViewModel variable named
vText. - Create a nesting named
Xml. - In
Xml, addSTRINGCONTENTand set its content fromvText. - In the same nesting, add the authorization header required by the receiving service.
- Call
RestPostand pass'Xml'as its final argument.
For example, the action expression has this structure:
vResponse:=selfVM.RestPost('https://service.example/endpoint','','','Xml')
In this example, vResponse receives the service response. Replace the URL and credentials with the values required by the external service. The content and headers are supplied by the Xml nesting.
Header names
When a request header contains hyphens, represent the header name in the nesting with HEADERMINUS_ and replace each hyphen with an underscore. For example, represent the HTTP header Ocp-Apim-Subscription-Key as:
HEADERMINUS_Ocp_Apim_Subscription_Key
This convention is used in the Mobile Money REST API example. A bearer token is also sent as an Authorization header when the remote service requires bearer-token authentication.
Work with the response
The REST call returns text that you can keep in a ViewModel variable. For a JSON response, use MDriven's JSON-to-model capability to turn the JSON string into model objects when you need to work with the returned data using your model and ViewModel tools. Keep the raw response available while developing the integration so that you can verify the service response and diagnose errors.
For example, a GET action can retrieve an external status response into vResponse; a following action can use the response after it has been converted into the model structure required by the application.
Authentication and request values
The user and pwd arguments provide credentials for services that use them. Services can also require request headers, such as an API subscription key or an Authorization bearer token. Put required headers in the parameter nesting and follow the external service's required authentication flow.
If a service issues tokens that expire, obtain a current token before calling protected operations. The Documentation:Rest API example notes this requirement for production calls that use JWT bearer tokens.
Expose a ViewModel carefully
To expose your own data, set the ViewModel's RestAllowed tagged value to true and deploy the updated model to the Turnkey site. A REST-exposed ViewModel can execute root-level actions for incoming requests, including GET and POST requests. This means an exposed ViewModel is not necessarily read-only.
Action placement in the root ViewModel class controls when actions run for REST POST:
| Action placement | When it executes for REST POST | Typical use |
|---|---|---|
| Before attributes in the root ViewModel class | Before sent values are applied | Look up objects using URL-coded variables |
| After attributes in the root ViewModel class | After sent values are applied | Act on or validate the applied values |
See Documentation:Rest Post for the REST POST action-order behavior. Restrict access to exposed services with the appropriate access control, and do not expose a ViewModel until its actions and returned data are safe for external callers.
Related integration options
Use REST when the remote system offers an HTTP REST endpoint. If the remote system instead provides SOAP, use selfVM.SoapCall; see Documentation:SOAP the protocol from the stone age. For broader integration guidance, see Documentation:Integration.