You can use REST POST actions in a REST-allowed ViewModel to prepare a request, apply posted values, and then process or validate the resulting data; this page is for MDriven Designer users exposing a POST endpoint from Turnkey.

What REST POST does

A REST POST request to a Turnkey REST endpoint supplies values to a ViewModel. MDriven matches the posted parameter names to ViewModel variables and exposed attributes, applies the values, executes root-level actions, saves changed values, and returns the ViewModel as JSON unless you override the response.

Configure the endpoint, URL formats, authorization, posted-value matching, and response overrides as described in HowTos:Expose REST Service. To call another REST service from a ViewModel, use selfVM.RestPost instead; that is a different use of REST POST.

Control the order of root actions

The position of a root-level action in the ViewModel controls whether it runs before or after posted values are applied.

Place the action	When it runs	Use it for
Before every root attribute	Before posted values are applied	Looking up objects or preparing state from URL-encoded ViewModel variables.
After the root attributes	After posted values are applied	Validating, transforming, or acting on the received data.

Arrange actions from top to bottom in the root ViewModel class. Do not rely on an action placed between attributes to make the request lifecycle clear: place preparation actions at the top and processing actions below the attributes.

Example: look up first, update second

Assume a REST-allowed ViewModel has a string variable named vCustomerId, an exposed attribute named RegistrationNumber, and two root actions.

1. Put an action such as FindCustomer before all root attributes. It can use vCustomerId, supplied in the URL, to find the target object.
2. Place RegistrationNumber in the root ViewModel so that POST data can supply its new value.
3. Put an action such as ValidateAndProcessRegistration below the root attributes. It sees the registration number after MDriven has applied the posted value.

A caller can then send a POST request with a URL parameter such as ?vCustomerId=... and a posted RegistrationNumber value. The lookup action runs first; MDriven applies the registration number; then the processing action runs.

Expose the POST endpoint

Before a client can POST to a ViewModel, enable REST access for that ViewModel and ensure that the caller is permitted by its access groups. The ViewModel name is part of the endpoint URL, and the root object identifier must be complete. See HowTos:Expose REST Service for the required RestAllowed tagged value, supported routes, ID formats, and access checks.

For example, the legacy Turnkey route uses this pattern:

TurnkeyRest/Post?command=vmname&id=rootobjref

The alternate route format is:

<host>/Rest/vmname/Post/rootobjref

Use a complete object ID, such as a GUID or xx|yyyy. A shortcut ID without a class identifier can resolve incorrectly.

Design the data the endpoint receives

For an exposed REST POST endpoint, MDriven matches incoming parameter names against ViewModel variables and attributes.

• Use string ViewModel variables for extra URL parameters. For example, a variable named vCustomerId receives a value sent as ?vCustomerId=123.
• Expose the attributes that the caller is allowed to set. A POST parameter named RegistrationNumber targets the ViewModel attribute with that name.
• Use a root action below the attributes to process data after it has been assigned.
• If the incoming POST structure is not known when you design the ViewModel, use Documentation:Receive post data not known at design time.
• If the caller sends JSON that must create or update modeled objects, use the JSON import approaches described in HowTos:Expose REST Service.

REST POST saves changed values to the database after processing. Both GET and POST normally return the ViewModel content as JSON.

Return a controlled response

Use the response controls documented in HowTos:Expose REST Service when the default ViewModel JSON is not the response your API needs.

Requirement	ViewModel member	Result
Return custom JSON or text	Root string attribute named RawJSon	MDriven returns its value instead of the complete ViewModel JSON.
Return a message body	vReturnMessage:String	MDriven returns the variable value as the response content.
Return a specific HTTP status	vReturnStatusCode:String	MDriven uses the named HTTP status value, such as Created or NotFound.

When consuming a REST service with an operator such as selfVM.RestPost, the variables vReturnStatusCode and vReturnMessage can also receive the status and response message from that service.

Receive raw request content

MDriven normally treats POST data as form fields matched to ViewModel columns. To receive an unstructured request body instead, add one of these columns where appropriate:

Column name	Receives
STRINGCONTENT	A non-form string request body.
BYTEARRAYCONTENT	A non-form binary request body, in a blob-compatible column.

For full request-content conventions, multipart uploads, content headers, and request headers when calling external services, see Documentation:OCLOperators RestPost.

Test and troubleshoot

1. Verify the ViewModel has REST access enabled and that the caller is authorized.
2. Send the request to the POST route, not the GET route. A GET request does not apply posted data.
3. Confirm that each posted parameter name matches the intended ViewModel variable or attribute name.
4. Check that preparation actions are above the root attributes and processing actions are below them.
5. Inspect the returned JSON, vReturnStatusCode, and vReturnMessage to identify endpoint errors.
6. When you need to inspect the outgoing request while consuming another service, use an HTTP echo service as suggested in HowTos:Expose REST Service.

See also

• HowTos:Expose REST Service
• Documentation:OCLOperators RestPost
• Documentation:Rest Services In MDriven
• Documentation:Receive post data not known at design time
• Documentation:Use c-sharp code to post to TurnkeyRest