¶ Request Body Types
The most common request body type in majority of modern APIs is JSON. This is the default value of Request Body Type field in Operations and usually you do not need to touch it at all. But sometimes you may need to send something else than JSON data in request body – like form-encoded string in standard OAuth2 authentication or binary file contents.
You can change the Request Body Type in the operations list or by opening operation Details.
Currently supported request body types are:
- Json – The default option. Send JSON in request body and automatically set
Content-Typeheader toapplication/json. - Form-data – Send multipart web form data as a request body, usually including some form fields and file attachment(s).
- X-www-form-urlencoded – Send simplified form data as a request body (with no file attachments). This is mainly used as a part of OAuth2 access token requests.
- Raw – Send text or binary message in request body.
¶ Form-data
Form-data requests send multipart form data, which is basically a web browser form submit, usually including a file attachment field and some more data (see documentation for more details: https://everything.curl.dev/http/multipart). In Postman the request may look like this:
To make such request, create a new operation. The Command is usually POST and you need to set Request Body Type to Form-data.
Then fill the form fields and their values in operation Request Body.
rootnode is always mandatory.- All form fields are on the second level. You can set the value as a constant here, in provider variables or with code as usual.
With form-data request you are sending HTTP headers in each form field – in case of file attachments these contain the file name or content type. You can access these headers by selecting the node in schema and opening Home / Headers. RESTwithUS is generating the mandatory headers automatically, but if needed, you can always overwrite them.
If you are sending a file attachment, you need to use ApiScript ADD_VALUE function to attach the file stream to the request body, see sample code below.
//Force user to select a file and add the file contents to image node
var
FileManagement: Codeunit "File Management";
TempBlob: Codeunit "Temp Blob";
FileInStream: InStream;
AllFilesFilterTxt: Label '*.*', Locked = true;
AllFilesDescriptionTxt: Label 'All Files (*.*)|*.*', Comment = '{Split=r''\|''}{Locked=s''1''}';
FileName: Text;
FileName := FileManagement.BLOBImportWithFilter(TempBlob, 'Choose File', 'Name', AllFilesDescriptionTxt, AllFilesFilterTxt);
TempBlob.CreateInStream(FileInStream);
ApiScriptRWU.ADD_VALUE('/image', FileInStream, FileName);
There is a built-in JSON support, too. If a form field contains JSON data (e.g. body field in the example below), you can define the JSON structure as usual.
- Set the form field Type to
Form Data JSON. - You can use the Payload / Import Payload function to create the schema from example.
If you are using Business Central tables and fields in the JSON schema, please set Type
Tableto the mainrootnode. More than one tables are currently unsupported.
The final request body contains auto-generated Content-Type header with a boundary string and all form fields in form-data format, separated by it.
¶ X-www-form-urlencoded
X-www-form-urlencoded requests send a simplified form data in request body. This is how the request may look like in Postman:
which is sending something like URL parameters string in request body:
client_id=3rCEQzwEHMT9PPvuXcClpe3v&client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421&redirect_uri=http%253A%252F%252Facmepaymentscorp.com&grant_type=authorization_code
The main use in modern APIs is in OAuth2 authentication, when requesting an access token. To make such request, create a new operation. The Command is usually POST and you need to set Request Body Type to X-www-form-urlencoded.
Then fill the form fields and their values in operation Request Body.
rootnode is always mandatory.- All form fields are on the second level. You can set the value as a constant here, in provider variables or with code as usual.
- Some settings like MaxOccurs or JSON Data Type has no effect.
Tip: If you are sending sensitive information like client ID or secret, place them into provider Variables.
The final request looks like this:
- RESTwithUS automatically generates correct
Content-Typeheader. - The data are sent as an URL encoded parameters string.
¶ Raw
Raw request body type is used for sending binary file contents or raw text data. The setup is very simple – just create a new operation. The Command is usually POST and you need to set Request Body Type to Raw.
The request body schema has just two nodes: Mandatory root node and a second node containing the request data. If you want to send binary file contents, set the node to Type File.
You need to use ApiScript ADD_VALUE function to attach the file stream to the request body, see sample code below.
//Force user to select a file and add the file contents to file node
var
FileManagement: Codeunit "File Management";
TempBlob: Codeunit "Temp Blob";
FileInStream: InStream;
AllFilesFilterTxt: Label '*.*', Locked = true;
AllFilesDescriptionTxt: Label 'All Files (*.*)|*.*', Comment = '{Split=r''\|''}{Locked=s''1''}';
FileName: Text;
FileName := FileManagement.BLOBImportWithFilter(TempBlob, 'Choose File', 'Name', AllFilesDescriptionTxt, AllFilesFilterTxt);
TempBlob.CreateInStream(FileInStream);
ApiScriptRWU.ADD_VALUE('/file', FileInStream, FileName);
The final request contains auto-generated Content-Type header (RESTwithUS fills it based on the file type) and file binary data in request body.
Tip: You can send almost any kind of data with Raw requests. Just pass the request body into a
Textnode and if needed, update request headers.
