You can use RestPost in a ViewModel action to send data, files, and HTTP headers to an external REST service and read its response.

What RestPost does

RestPost is an EAL operator on selfVM. It is available only in a ViewModel context. It sends an HTTP POST request to a target URL and returns the response body as a string.

Use RestPost when the remote service expects data in the request body, such as form fields, multipart file uploads, or a single string payload. For GET requests, use RestGet. For browser-oriented file downloads, use RestDownload.

The data and headers for a request are defined by a blue nesting (a nested ViewModel class). The names of columns in that nesting control how MDriven formats the HTTP request.

Call RestPost from an action

The documented REST operator form is:

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

• targeturl is the remote endpoint URL.
• user and pwd provide optional authentication. See Authentication.
• optionalnestingwithheadersAndUploadValues supplies request headers, content headers, and POST body values.

Store the returned response body in a string variable. For example, if the ViewModel has a string variable named vResult and a nesting named RequestedHeaders:

vResult := selfVM.RestPost('https://testmdriven.requestcatcher.com/test', '', '', selfVM.Nestings.RequestedHeaders)

The remote service defines the URL, authentication method, headers, and body format that you must send. Test the service independently when possible, then model the same request in the nesting.

Build the request nesting

Create a nesting in the ViewModel and add columns for the values to send. MDriven interprets certain column names as instructions. All other columns are payload values unless a selected content mode says otherwise.

Choose one content mode

RestPost and RestPut can send content. RestGet and RestDelete do not send content.

Nesting column name	Resulting request content	Example
STRINGCONTENT	Sends the value as StringContent, rather than multipart form data. Use this as the single body-value column, apart from header columns.	A string containing XML generated by another ViewModel.
BYTEARRAYCONTENT	Sends the value as ByteArrayContent, rather than multipart form data. Use this as the single body-value column, apart from header columns.	A byte array containing a binary document.
HEADERMINUS_Content_Type with value application/x-www-form-urlencoded	Sends the other columns as FormUrlEncodedContent: a dictionary of string name/value pairs.	client_id, client_secret, and grant_type fields for a token request.
No single-content or URL-encoded mode column	Sends the values as MultipartFormDataContent by default.	A form with ordinary fields and an uploaded file.

Do not combine STRINGCONTENT or BYTEARRAYCONTENT with other ordinary payload columns. These modes represent one complete request body.

Add ordinary payload values

In the default multipart mode, an ordinary column becomes a multipart form-data value. For example, a nesting with title and description columns sends those values as form fields.

For URL-encoded content, set HEADERMINUS_Content_Type to application/x-www-form-urlencoded. MDriven then treats all other non-header columns as string values in a form URL-encoded dictionary.

Send a file in multipart form data

To send a byte-data column named attachment, add matching control columns:

Column	Example value	Purpose
attachment	The file byte data	The multipart file content.
FILENAME_attachment	photo.jpg	Sets the file name for attachment.
CONTENTTYPE_attachment	image/jpeg	Sets the content type for attachment.

The suffix after FILENAME_ and CONTENTTYPE_ must exactly match the byte-data column name. Each byte-data part in a multipart request can have its own content type.

Send arrays

Some services expect indexed fields, for example:

my_array[0] = value1
my_array[1] = value2

Subnestings under the nesting supplied to RestPost are handled as arrays. MDriven repeats the parameter name for each item and uses the first ViewModel column in each subnesting item as that item's value.

Add headers

HTTP headers belong either to the request or to its content. Use the correct prefix because services commonly require authentication as a request header and media information as a content header.

Column-name pattern	Header destination	Header name	Example
HEADER_xxx	Content headers	xxx	HEADER_Authorization
HEADERMINUS_xxx	Content headers	Replaces underscores in xxx with dashes	HEADERMINUS_Content_Type becomes Content-Type
DEFAULTREQUESTHEADER_xxx	Request headers	xxx	DEFAULTREQUESTHEADER_Authorization
DEFAULTREQUESTHEADERMINUS_xxx	Request headers	Replaces underscores in xxx with dashes	DEFAULTREQUESTHEADER_X_Custom_Header becomes X-Custom-Header

For example, use DEFAULTREQUESTHEADERMINUS_Authorization when the service requires an Authorization request header. Use HEADERMINUS_Content_Type when the header describes the POST body.

GET compatibility setting

FORCEREQUESTCONTENTTYPE forces a Content-Type header onto a GET request by adding empty content and applying the header to it. This is not a standard GET request and should be avoided unless the target framework requires it. Its presence also enables other headers on that GET request.

Authentication

When both user and password values are provided, RestPost builds a Basic authentication request header using the user and password.

When user is Bearer, MDriven treats pwd as a bearer token and sends it in the authentication header. The user value is retained as supplied, which matters when a service is case-sensitive.

For example:

vResult := selfVM.RestPost('https://api.example.com/items', 'Bearer', vAccessToken, selfVM.Nestings.RequestedHeaders)

Read the response

RestPost returns the response body as a string. Add these root ViewModel string variables when you need the HTTP result details:

Variable	Contains
vReturnStatusCode	The status returned by the REST call.
vReturnMessage	The reason message returned by the REST call.

For a binary response that cannot be represented as UTF-8 text, add a column named base64ReturnStream in the supplied nesting and set it to Boolean true. The returned string then contains the response stream encoded as Base64. For a GET download that should be handled as a Blob, see RestDownload.

Handle success and failure

You can add actions named OnSuccess and OnFail in the request nesting.

• OnSuccess runs when the call succeeds. For example, set a variable that enables a follow-up action after the remote service accepts the upload.
• OnFail runs when the call fails. For example, renew an expired access token before retrying the request.

To retry the action that made the REST call once, use selfVM.ExecuteCurrentActionAgainOnce from OnFail. This retries only one time; if the retry fails, the call remains failed. Renew any expired token before invoking the retry.

Example: upload an image

This example sends an image file as multipart form data and stores the response.

1. Add root variables

In a ViewModel named TestApi, add these string variables:

• vResult for the raw response body.
• vReturnStatusCode for the HTTP status.
• vReturnMessage for the response reason message.

2. Create the request nesting

Create a blue nesting named RequestedHeaders. Add the following columns:

Column	Value example
attachment	The image byte data.
FILENAME_attachment	image.jpg
CONTENTTYPE_attachment	image/jpeg

Because no single-content or URL-encoded mode is selected, the request uses multipart form data. The file part receives the configured filename and content type.

3. Add the action expression

Add an Action column and assign the response to vResult:

vResult := selfVM.RestPost('https://testmdriven.requestcatcher.com/test', '', '', selfVM.Nestings.RequestedHeaders)

A request inspection endpoint can show how the nesting became a multipart HTTP request, including the multipart boundary, filename, content type, and any headers. For general REST debugging, the receiving-service guidance in Expose REST Service recommends using an echo service to inspect request parameters.

Related REST behavior

If you are implementing an endpoint that receives requests in MDriven rather than calling an external service, see Rest Post and Expose REST Service. A REST-enabled ViewModel requires the RestAllowed tagged value. Incoming non-form string content can be received in a STRINGCONTENT column; incoming binary content can be received in a Blob-typed BYTEARRAYCONTENT column.

See also

• Documentation:Rest Services In MDriven
• Documentation:OCLOperators RestGet
• Documentation:OCLOperators RestDownload
• Documentation:Rest Post
• HowTos:Expose REST Service