Handling JSON representations of REST resources
If you are creating resources which have JavaScript Object Notation (JSON) data representation and you want to have your outgoing requests in JSON data format and response received in JSON format, you must set the root element correctly. Ensure that you create your IS document representations in accordance with the structure of the data.
JSON data format typically has data organized in key:value pairs enclosed within { } brackets. A JSON data snippet may not have a root element, so if you want to send requests using an IS document (whose name represents a data root), you need to exclude that root element because you may want only the child key and value elements to be sent. Similarly, in response, you may want to exclude or consider the root element based on the representation of the resource from the SaaS provider. To handle such cases, consider the Add Parent option.
To add a root element
1. From the Request or Response Body panel, right-click and select a document type.
2. Click Next to configure the request or response body.
The request or response body dialog box appears. By default, the name of the doctype is displayed.
3. In the Configure section, click Add Parent to add a root element to the body of the request or response. By default, the Add Parent option is cleared.
The root element of the payload or document type will have the specified new root element. For requests, if the Add Parent option is not selected, outgoing requests will have key:value pairs without the root element, for example, data - {"first": "John", "last": "Doe"}. For responses, it means that the root is excluded in the response.
Note:
If you add the parent, only then the name is added as the root element in the body and the root element is added, else the request/response name is not added as the root element.
If the JSON response has just key:value pairs and no top level root element, you can have a document type with custom root, having the expected key:value pairs. In the resource response, Add Parent should be unchecked. For example, {"first": "John", "last": "Doe", "age": 20, "sex": "M", "salary": 50000, "registered": true }. In this example, the parent is not required.
If the JSON response has key:value pairs with a top level parent root present, you can select the Add Parent option in response as your document matches the response. For example, { "error": { "errors": [ { "domain": "local", "reason": "credError", "message": "Invalid Credentials" } ], "code": "401", "message": "Invalid Credentials" }}. This example already has a root - error, so your IS document type can be mapped if its root name is error too. Within it, the child elements appear as in the response data. It is important to create appropriate IS documents and set the correct property value for the responses to be mapped correctly.