¶ Importing and Setting up JSON Body Structure
In API requests that are sending or receiving more complex data you need to set up the JSON request or response structure. This means turning JSON data like this:
into RESTwithUS definition that tells the application, how to create the request JSON or process the response:
You can create the JSON body definition in an Entity or in operation request / response:
- From entity list open Schema Definition.
- From operations list open Request Body or Response Body.
Tip: You can define the JSON schema just once on entity level and then reuse it in multiple operations using the same schema. See Using Entity Schema in Request/Response in the entity guideline.
For non-JSON requests (like form-data or binary file contents) see guideline Request Body Types.
¶ Import Payload
Initially the schema is empty. You can of course define it by yourself, but much easier is to use function Payload / Import Payload, paste an example of JSON request or response and press OK:
RESTwithUS will generate schema structure for you and you just need to map it to Business Central tables and fields:
The rest of this guideline explains different settings and options, that you can use when working with JSON schema definition.
¶ Tables
Probably the first thing to do is to identify the JSON nodes that contain whole records and map them to Business Central tables. Usually you can identify them quite easily by the JSON Data Type column – they have value Object for a single record node or Complex Array for record array node.
For both nodes do following actions:
- Set Type to
Table. - Select the right Business Central table no. in column Object ID.
- Select matching RESTwithUS entity in column Entity ID. Entities are used for storing Connections between Business Central records and records in an external system.
Tip: If you don't have an entity yet, just create a simple line in entities list (select Entities on a provider). You can add more settings later.
¶ Fields
Second step is to match fields between Business Central and an external system. When making a request, these fields will be automatically filled in with a value from Business Central record – and during response those values can be saved into matching Business Central fields.
For each matching field do following actions:
- Set Type to
Field. - Select the matching Business Central field no. in Object ID column. RESTwithUS will offer you a list of fields from a parent
Tablerecord node.
Tip: You don't need to match all fields, just those you are interested in. Plus you can almost always delete the lines with not needed nodes.
Matching the fields does not necessarily mean that the data are written to Business Central from API operation response. See guideline Updating Data in Business Central for details.
¶ Mapping Type
Mapping Type column is used for marking significant request/response JSON nodes like unique ids, tokens etc. RESTwithUS is then using this information to create and process Connections between Business Central records and records in an external system.
¶ External ID
Select External ID in Mapping Type column for a node that contains the unique identifier of a record in an external system:
In this example you have two such nodes, conveniently called id. But they are both from different tables and different entities – one id is for a Customer and second for his Shipping Address. For both nodes do following actions:
- Set Mapping Type to
External ID. - Select matching RESTwithUS entity in column Entity ID. If you have already selected the entity in a parent
Tablenode, RESTwithUS will fill it automatically.
¶ Description
Description Mapping Type marks a node that contains human readable and quite unique description of the record. RESTwithUS usually does not use the description for any kind of processing, but saves it in the Connections to help user identify the records.
For a Customer record the best human readable identifier is his name, and you can select the name field in Shipping Address, too (although address would probably work here as well). For both nodes do following actions:
- Set Mapping Type to
Description. - Select matching RESTwithUS entity in column Entity ID. If you have already selected the entity in a parent
Tablenode, RESTwithUS will fill it automatically.
¶ Embedded ID
Embedded ID marks nodes that contains an id of a record in an external system, but there is not whole record in JSON, only the link to it.
Let's have an example of a customer record:
There is a countryId node containing the id of a country in an external system. But Business Central is using country code as a primary key – and when making a request, RESTwithUS will need to "translate" for example US country code to its id in an external system (or backwards in a response).
For each node with an embedded id (both countryId nodes in the example) do following actions:
- Set Mapping Type to
Embedded ID. - Select matching RESTwithUS entity in column Entity ID. RESTwithUS will match the Business Central record with a record in an external system based on the entity Connections.
If RESTwithUS for example, exports data of a customer with a US country, it takes a look to the Country entity connections and gets the External ID of the record from there. It works in similar way for response – the countryId from JSON is "replaced" by the country code from Business Central.
Tip: Obviously you would need to have valid Connections for each country, otherwise the operation will fail. If the country records are already existing in an external system, you can make the connections with GET Multiple Records operation – or create the countries in an external system with a POST operation.
¶ Token
Tokens are mainly used for a Token authentication type to mark the node containing an authentication token.
Let's have an example of a simple authentication API operation: You are providing user's e-mail and password in a POST JSON body and if the authentication was successful, the API returns following response:
RESTwithUS now needs to save the token for later use in other operations – and in this case, each user may have a different token. Plus there is usually some expiration on tokens, they stop to be valid after some time.
The authentication token is returned in token JSON node, so do following actions on it:
- Set Mapping Type to
Token. - Select RESTwithUS entity for storing the session tokens in column Entity ID. The tokens will be saved in the entity Connections.
Please note that for the connection to work, you at least need to mark some node as an External ID. Plus if you plan to use different tokens for different users (each user has his own session), save the username into the connection Ext. Description.
Now set up the expiration time. Select the token node and open Home / Details from the menu:
On the Mapping tab set the token expiration in a field Token Expiration (minutes) – e.g. if the token expires after a day, put 1440 there (60 minutes * 24 hours).
¶ Min/Max Occurs
MinOccurs and MaxOccurs settings defines:
- If the node is required or optional.
- If it is just simple JSON node or an array.
- Each array node is marked with MaxOccurs
Unbounded. - Nodes with MinOccurs
Onceare required. If there are no data provided for the node in a request, the operation ends with error. E.g. in the example the customer is required to have at least one shipping address. - Nodes with MinOccurs
Zeroare optional.
You can make some additional settings in the node details (select Home / Details from the menu):
- Empty Value on Zero Occurs determines the optional node behaviour, if there are no data provided. Select
Skipto delete the node from resulting JSON andEmpty Objectto include it as an empty object, empty array or anullvalue in case of some basic data types. - Conflict in Child Nodes sets the behaviour of child nodes in a response.
- With
Ignore Missing SchemaRESTwithUS will not check, if the JSON is 1:1 to schema – the API can send some additional JSON nodes which are not presented in the schema and it does not matter at all. (This is the default option.) - With
Errorsettings RESTwithUS always checks, if the response JSON is 1:1 to schema – so if the API provider for example adds a new field to the JSON, the operation will now end up with error.
- With
¶ JSON Data Type
JSON Data Type defines the data type of the node in JSON. RESTwithUS is mostly setting the data type automatically based on the example JSON or Business Central field type.
But in case of need, you can change the data type manually, too. This can be for example useful, if you want to have numbers exported with enclosing quotes and a specific format, i.e. instead of this JSON:
{
"number":1.2
}
you want something like this:
{
"number":"1,2"
}
In such case change the JSON Data Type from Number to String and define the formats in provider details.
For more details see the JSON Data Types guideline.
¶ Indentation
You can move the nodes to the left or to the right with Indentation / Decrease Indent or Indentation / Increase Indent functions:
¶ Node Details
For each node you can specify additional details with Home / Details action. Fields in these details can differ based on the node settings:
- Occurence tab – See the Min/Max Occurs section.
- Modify Value tab – See guideline Using Regular Expressions.
- Connection Management tab – See guidelines Connections and Updating Data in Business Central.
- Variables tab – See guideline Using RESTwithUS Variables.