View source for Documentation:OCLOperators RestPost

<message>Write the content here to display this box</message>
===== Rest (representational state transfer) =====
[[Documentation:OCLOperators RestGet|RestGet]], [[Documentation:Rest Post|Rest Post]], [[Documentation:Rest Put|RestPut]], [[Documentation:Rest Delete|RestDelete]], and [[Documentation:OCLOperators RestDownload|RestDownload]] are all operators on the selfVM variable only available in ViewModels.

These operators enable you to get or put information into external REST-based services.

These operators work by adding a ViewModel Nesting/Class that has data and additional headers.

'''Rest explained:''' [[wikipedia:Representational_state_transfer|Representational_state_transfer]]

===== General Rules and How to Use Headers in HTTP and Rest =====
Please read about the difference between request headers and content headers.

==== Nesting Columns Starting According to ====
For '''Content'''
* '''STRINGCONTENT''' If there's a column named, then the request will be filled with StringContent(value as string), Not a multipartmessage, and you should only have this single column except columns for headers
* '''BYTEARRAYCONTENT''' If there's a column named, then the request will be filled with ByteArrayContent(value as byte[]), Not a multipartmessage, and you should only have this single column except columns for headers
* '''FILENAME_'''xxx  the value is used as a filename in a MultipartFormDataContent expecting a xxx column with byte data for the file content
* '''CONTENTTYPE_'''xxx  the value is used as content type in a MultipartFormDataContent expecting a xxx column with byte data for the file content. Clarification - this allows for unique Content types on each byte array in a multipart content message  (NEW! 2025-12-03) 
* '''HEADER_'''xxx  the value is added to the content as Headers.Add(xxx,value)
* '''HEADERMINUS_'''xxx the value is added to the content with the name underscores converted to dashes. I.e. as Headers.Add(xxx.Replace('_','-'),value)
* '''HEADERMINUS_Content_Type ='application/x-www-form-urlencoded'''' will force the Post/Put into url-encoded-mode - all other columns are assumed to be strings that will be sent with a dictionary of name /values as FormUrlEncodedContent(theValuesForUrlEncoded)
The default content is MultipartFormDataContent, (values as dictionary) for example, used in the [[Documentation:Oauth2|Oauth2 implementation for server to server authentication.]]

Also, note that content can only be sent in REST '''POST''' and '''PUT'''.

For the '''Request'''
* '''DEFAULTREQUESTHEADER_'''xxx the value is added to the request as client.DefaultRequestHeaders.Add(xxx,value)
* '''DEFAULTREQUESTHEADERMINUS_'''xxx the value is added to the request with the name underscores converted to dashes. I.e. as client.DefaultRequestHeaders.Add(xxx.Replace('_','-'),value)
* '''FORCEREQUESTCONTENTTYPE''' can be used to force adding a '''Content Type''' header to '''GET''' request. Some frameworks need it, but it is actually an invalid request. It's implemented as adding an empty content and adding a header to that empty content. '''''NOTE!!''''' this should be ''avoided'' if possible!!
** Note also that using '''FORCEREQUESTCONTENTTYPE''' will enable you to add other headers to a Get request. Needed for several Frameworks, but again, not according to standard.
For the '''returned''' string result:
* '''base64ReturnStream''' - when this column is found and evaluates to Boolean true, the string returned is really as base64 of the returned stream. This is important if the returned binary stream cannot be represented with utf-8. 
* '''vResponseHeaders''' - if such a variable of type string is present - all response headers will be added as a return separated list 
'''See a further description here:''' [[Documentation:Rest Services In MDriven|Rest Services In MDriven]]

* '''onfail''' - Action named OnFail placed in the nesting will be executed if the call that used the nesting failed. A special action suitable to execute on onfail is selfVM.[[Documentation:SelfVM|ExecuteCurrentActionAgainOnce]] - the action using the nesting will then be executed once more (only once more, if it fails again it is busted). Prior to calling selfVM.ExecuteCurrentActionAgainOnce you may want to renew any accesstoken that may have lapsed and being the reason for the failed call
* '''onsuccess''' - Action named OnSuccess placed in the nesting will be executed if the call that used the nesting succeed - consider setting a variable here that is used to enable some action-column that should follow a success

=== Rest Checklist ===
'''The URL''' = the address of the remote service

'''User & Password''' = if provided, will build up an Authentication request header of type basic ( == 'basic '+(user+':'+password).stringtobase64 ) - when user == Bearer we will assume that the password is a bearer token that will be passed in an authentication header ( == Bearer tokenincleartext) (Note: some services are case sensitive on Bearer - we use the value you give in user un-altered).

'''Nesting with values''' = name of an existing Nesting (blue) in your ViewModel (green).

In the Nesting, you can add additional columns to control how data is sent to the remote service.

It is the remote service that defines what you need to send - but you will quickly need to decide if the remote service expects content headers, request headers, and payload in a specific format (one of MultiPartContent. StringContent or UrlEncodedContent). All values you send in the payload will be from the values in the Nesting - apart from any parameters, you can send in the URL directly (Get and Delete operate this way).

There are 3 kinds of values in the payload; Content headers (usually define what the content is), Request headers (usually where authentication information goes), and plain data as payload. 

'''Payload:''' We separate between the 3 kinds (MultiPartContent. StringContent or UrlEncodedContent) of payload with a naming convention of the nesting columns name (begins with) - see above.

'''Arrays in Payload''': You sometimes need to send arrays in this format:

my_array[0]  value1

my_array[1]  value2

SubNestings from the NestingsWithParams will now be handled as such arrays and the name of the param will be repeated once per item in the list - the value will be the first ViewModel column in such subnesting.

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

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

{{Edited|July|12|2025}}

Example

This example uses a ViewModel named <code>TestApi</code> to send an image file to an external service

=== 1. The ViewModel Setup ===
To handle the request and its response, we define a set of variables in the root of the ViewModel:

* '''<code>vResult</code>''': A string variable that stores the raw body of the response returned by the API.
* '''<code>vReturnStatuscode</code>''': Stores the HTTP status (e.g., "OK" or "200").
* '''<code>vReturnMessage</code>''': Stores the descriptive reason code from the server.

[[File:Documentation OCLOperators RestPost 1770460786419.gif|thumb|658x658px|ViewModel Setup]]









We create a Nesting (blue box) named '''<code>RequestedHeaders</code>'''. Instead of standard data, we use "Magic Column Names" to tell MDriven how to format the file upload
{| class="wikitable"
|'''Column Name'''
|'''Expression'''
|'''Purpose'''
|-
|'''<code>attachement</code>'''
|<code>vCurrent_TestApi.image</code>
|The actual byte data of the image.
|-
|'''<code>FILENAME_Attachement</code>'''
|<code>'image.png'</code>
|Tells the receiver the name of the file being sent.
|-
|'''<code>CONTENTTYPE_attachement</code>'''
|<code>'image/png'</code>
|Tells the receiver this is a PNG image (MIME type).
|}
<blockquote>'''Note:''' The names <code>FILENAME_</code> and <code>CONTENTTYPE_</code> must be followed by the exact name of the data column they refer to (in this case, <code>attachement</code>).</blockquote>

=== 3. The EAL Execution ===
The actual call is triggered by an Action column. Using '''EAL (Executable Action Language)''', we execute the operator:

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

* '''URL''': The destination (RequestCatcher is used here for testing).
* '''User/Pass''': Left empty (<code><nowiki>''</nowiki></code>) in this example.
* '''Nesting''': Points to our <code>RequestedHeaders</code> nesting to provide the payload.

=== 4. Verifying the Result ===
By using a tool like '''RequestCatcher''', you can see exactly how MDriven converted your ViewModel columns into an HTTP request:

* The '''Content-Type''' is automatically set to <code>multipart/form-data</code>.
* The image data is wrapped in a "boundary" along with its filename and specific content type.
* The UI displays the response, showing "OK" in the status variables if the "handshake" was successful.

[[File:Documentation OCLOperators RestPost 1770460973338.png|thumb|642x642px|Using <code>requestcatcher.com</code>, we can see the raw HTTP request generated by MDriven. The tool confirms that the request was sent as <code>multipart/form-data</code>. You can see the distinct "boundaries" that MDriven created to separate the image data, the filename, and the content type, proving that the "Nestings Columns" in the ViewModel were correctly translated into a standard web request]]
[[File:Documentation OCLOperators RestPost 1770460997248.png|thumb|636x636px|'''Successful API Execution.''' This screen shows the live application after the "TEST A PI" action has been triggered. The <code>Results</code> field displays "request caught," which is the direct response from the server. The <code>v Return Message</code> and <code>StatusCode</code> variables both show "OK," confirming a successful '''HTTP 200''' handshake. This is the final result the end-user sees when the '''EAL''' (Executable Action Language) logic completes successfully]]
[[Category:EAL (Executable Action Language)]]
[[Category:External communication]]