OCLOperators RestPost
No edit summary
No edit summary
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
===== Rest =====
===== Rest =====
[[OCLOperators RestGet|RestGet]], [[OCLOperators RestPost|RestPost]], RestPut, RestDelete and [[OCLOperators RestDownload|RestDownload]] are all operators on the selfVM variable only available in ViewModels.
[[OCLOperators RestGet|RestGet]], [[OCLOperators RestPost|RestPost]], RestPut, RestDelete, and [[OCLOperators RestDownload|RestDownload]] are all operators on the selfVM variable only available in ViewModels.


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


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


===== General rules and how to use headers in http and rest =====
Rest explained: https://en.wikipedia.org/wiki/Representational_state_transfer
Please read about the difference about request headers and content headers. https://en.wikipedia.org/wiki/Representational_state_transfer


==== Nesting columns starting according to ====
===== 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'''
For '''Content'''
* '''STRINGCONTENT''' If the there's a column named then the request will be filled with StringContent(value as string)
* '''STRINGCONTENT''' If there's a column named, then the request will be filled with StringContent(value as string)
* '''FILENAME_'''xxx  then the value if used as filename in a MultipartFormDataContent expecting a xxx column with byte data for the file content
* '''FILENAME_'''xxx  then the value is used as a filename in a MultipartFormDataContent expecting a xxx column with byte data for the file content
* '''HEADER_'''xxx  then the value is added to the content as Headers.Add(xxx,value)
* '''HEADER_'''xxx  then the value is added to the content as Headers.Add(xxx,value)
* '''HEADERMINUS_'''xxx  then the value is added to the content with the name underscores converted to dashes. I.e. as Headers.Add(xxx.Replace('_','-'),value)
* '''HEADERMINUS_'''xxx  then 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 [[Oauth2|Oauth2 implementation for server to server authentication]]
The default content is MultipartFormDataContent, (values as dictionary) for example used in the [[Oauth2|Oauth2 implementation for server to server authentication]]


Line 22: Line 25:
* '''DEFAULTREQUESTHEADER_'''xxx then the value is added to the request as client.DefaultRequestHeaders.Add(xxx,value)
* '''DEFAULTREQUESTHEADER_'''xxx then the value is added to the request as client.DefaultRequestHeaders.Add(xxx,value)
* '''DEFAULTREQUESTHEADERMINUS_'''xxx then the value is added to the request with the name underscores converted to dashes. I.e. as client.DefaultRequestHeaders.Add(xxx.Replace('_','-'),value)
* '''DEFAULTREQUESTHEADERMINUS_'''xxx then 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. Is it needed by some frameworks, but is actually an invalid request. It's implemented as adding a empty content and adding a header to that empty content.
* '''FORCEREQUESTCONTENTTYPE''' can be used to force adding a '''Content Type''' header to '''GET''' request. It is needed by some frameworks, but 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!!
See further description here [[Rest Services In MDriven]]
** 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.  
See a further description here: [[Rest Services In MDriven]]
 
=== 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.
 
[[Category:OCLOperators]]
[[Category:OCLOperators]]

Revision as of 08:39, 3 March 2023

Rest

RestGet, RestPost, RestPut, RestDelete, and 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: https://en.wikipedia.org/wiki/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)
  • FILENAME_xxx then the value is used as a filename in a MultipartFormDataContent expecting a xxx column with byte data for the file content
  • HEADER_xxx then the value is added to the content as Headers.Add(xxx,value)
  • HEADERMINUS_xxx then 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 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 then the value is added to the request as client.DefaultRequestHeaders.Add(xxx,value)
  • DEFAULTREQUESTHEADERMINUS_xxx then 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. It is needed by some frameworks, but 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.

See a further description here: Rest Services In MDriven

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.

This page was edited 3 days ago on 03/26/2024. What links here