¶ JSON Data Types
¶ Basic Information
You can find JSON Data Type column in any JSON schema (for operation request, response or entity):
This column specifies, how RESTwithUS formats the node in the resulting JSON (in request) – or what kind of data RESTwithUS expects in the API response.
RESTwithUS usually sets the JSON Data Type automatically based on some conditions like:
- When using Payload / Import Payload function the data type is retrieved from the JSON sample.
- If a Business Central field is selected, the data type is selected based on the field data type (e.g.
Stringfor aTextfield). - If MaxOccurs =
Unbounded, then the data type isSimple ArrayorComplex Array.
But if you need to retype the value in JSON, you can select it manually (e.g. if you have a Text field in Business Central, but you are saving numerical values into it and want to export it in JSON as a number, without quotes, then change the JSON Data Type to Number).
Tip: If you want to have better control over JSON node outputs, set JSON Data Type to
Stringand then fine tune the formats in provider details (select a provider from the list, open his Details and look for the Formats tab).
¶ How to Set Node Value with Code
You can set any node value using ADD_VALUE function from the API Script RWU codeunit. Let's have a few examples:
//Add a Customer record to the root node
ApiScriptRWU.ADD_VALUE('/root',Customer);
//Manually set the value of a node for different data types
ApiScriptRWU.ADD_VALUE('/root/name','Progressive Home Furnishings');
ApiScriptRWU.ADD_VALUE('/root/number',1);
ApiScriptRWU.ADD_VALUE('/root/boolean',true);
//Manually add two phone numbers into phones array node
ApiScriptRWU.ADD_VALUE('/root/phones','+420 123 456 789');
ApiScriptRWU.ADD_VALUE('/root/phones','+420 123 456 789');
¶ Boolean
Boolean data type exports to JSON as true or false, without quotes:
{
"boolean-true":true,
"boolean-false":false
}
If you do not provide any value in request boolean node, it will be skipped by default.
To avoid this, either set the default value to
trueorfalse– or set MinOccurs toZeroand Empty Value on Zero Occurs toEmpty Objectto exportnullvalue.
¶ String
String data type exports to JSON as a text in quotes:
{
"name":"Progressive Home Furnishings",
}
¶ Date
RESTwithUS does not have date JSON Data Type. Date fields are instead exported as a String:
{
"date":"2020-08-13 08:20:00",
}
And you can set the date format in provider Details, tab Formats:
These settings are applied during API response parsing, too – so if your dates do not load correctly, check the date formats.
¶ Number
Number data type exports to JSON as a number without quotes and with dot as a decimal separator:
{
"integer":1,
"decimal":15.32
}
If you do not provide any value in request number node, it will be skipped by default.
To avoid this, either set the node default value to
0– or set MinOccurs toZeroand Empty Value on Zero Occurs toEmpty Objectto exportnullvalue.
¶ Null
Null data type writes null value into JSON output:
{
"empty-node":null
}
To export
nullvalue in request JSON node, set MinOccurs toZeroand Empty Value on Zero Occurs (in node Details) toEmpty Object.
¶ Object
The object contains data of a single record (e.g. Customer) and may contain children objects, arrays, etc.:
{
"id": 1,
"no": "01121212",
"name": "Spotsmeyer's Furnishings",
"address": "612 South Sunset Drive",
"city": "Miami",
"countryCode": "US",
"contact": {
"name": "John",
"surname": "Smith",
"email": "john.smith@gmail.com"
}
"phones": ["123456789","999999999"]
}
Usually the Type of the node is set to Table and you set a Business Central record as a node value:
ApiScriptRWU.ADD_VALUE('/root',Customer);
¶ Simple Array
Simple array data type exports to JSON as an array of values (text, number, etc.):
{
"phones": ["123456789","999999999"],
"ids": [1,2,3]
}
When using simple array in a schema, you can use one-line syntax:
ApiScriptRWU.ADD_VALUE('/root/phones','+420 123 456 789');
ApiScriptRWU.ADD_VALUE('/root/phones','+420 123 456 789');
Or you can use two-line syntax with Type = Table node and pass a Business Central record into it:
IF Contact.FINDSET() THEN REPEAT
ApiScriptRWU.ADD_VALUE('/root/phones',Contact);
UNTIL Contact.NEXT() = 0;
¶ Complex Array
The complex array is an array of JSON objects:
[
{
"no":"01121212",
"name":"Spotsmeyer's Furnishings",
},
{
"no":"01445544",
"name":"Progressive Home Furnishings",
}
]
Usually the Type of the node is set to Table and you can add multiple Business Central records to the node value:
IF Customer.FINDSET() THEN REPEAT
ApiScriptRWU.ADD_VALUE('/root',Customer);
UNTIL Customer.NEXT() = 0;