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 exclude root properties 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 excludeRoot property exposed through the connector development plug-in.

For requests, if the property is selected, outgoing requests will have key:value pairs without the parent root, for example, data - {"first": "John", "last": "Doe"}. For responses, it means that the root is excluded in the response. Further, it may have two or more cases.

The following information describes how you should create the corresponding IS documents and how the property should be set:

1. If the JSON response has just key:value pairs and no top level parent root, you can have a document type with custom root, having the expected key:value pairs. In the response resource, excludeRoot should be set to true or the property should be selected. For example, {"first": "John", "last": "Doe", "age": 20, "sex": "M", "salary": 50000, "registered": true }.

2. If the JSON response has key:value pairs with a top level parent root present, you can set the exclude root to false 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.