Sending and Receiving JSON and XML Part 1

[#1]

• GUIDE CONCEPT
• Step 1: Completed Example
• Step 2: Sending JSON Based Requests

Learn how to send and receive JSON and XML payloads to SOAP and REST services.

 

GUIDE CONCEPT

This project will introduce how to create services that can send and receive XML and JSON payloads.

Following the steps in this guide, you will develop services to handle, send, and receive XML and JSON.

We will teach you how to use the ThingWorx Platform to handle REST requests and send payload for external SOAP and REST services.

YOU'LL LEARN HOW TO

• Efficiently handle, send, and receive XML and JSON in ThingWorx
• Make requests to external REST services
• Make requests to external SOAP services

NOTE:  The estimated time to complete all parts of this guide is 60 minutes.

Step 1: Completed Example

Download the attached JSONXMLEntities.zip from attached files and import it into ThingWorx Composer.

In this tutorial, you will learn how to make and handle requests to live external REST and SOAP services. The entities file provided contains the following files and entities as a completed version of the scenario that will be covered:

Name	Description
JSONRequestThing	Thing with examples of making requests using JSON
XMLRequestThing	Thing with examples of making requests using XML
JSONHandlerThing	Thing with examples of handling JSON requests and returning organized data
XMLHandlerThing	Thing with examples of handling XML requests and returning organized data

This guide will use services provided by Microsoft Azure. Create a free account to utilize Microsoft Azure Web API services. In order to utilize this web api, obtain a FREE API key from Microsoft Azure Portal using these Microsoft Azure instructions. You are able to use other Web APIs for this guide.

Follow the next steps in order to get started.

Step 2: Sending JSON Based Requests

Whether making a request to a public web service or sending data to a device running an application, ThingWorx is able to utilize different REST request methods (GET, POST, PUT, DELETE, etc) using the ContentLoaderFunctions Resource. This same resource provides services for XML payloads, but JSON is the default formatting for REST. See the "Sending XML Based Requests" section in this guide for working with XML.

This guide will not explain REST or REST methods, only how to use these REST methods.

To get started, create a Thing using the below steps. You will create new services in this Thing to make REST requests and add a service to help with HTML encoding.

NOTE: Examples of these services can be found in the JSONRequestThing entity, which is provided in the download.

1. In ThingWorx Composer, click the + New at the top of the screen.
2. Select Thing in the dropdown.
3. Name the Thing JSONRequestExample and set the Base Thing Template to GenericThing.
4. Click Save.
5. Click the Services tab.
6. Create a new service called EncodeQueryToHTML.
7. Add the following Input:
   
   

   Name	Base Type	Required
   query	String	True

8. Add the following JavaScript to help encode the string and return an HTML friendly string.

try {
    var result = "";

    if(query) {
        result =  query.replace(/&/g, "&").replace(/>/g, ">").replace(/</g, "<").replace(/"/g, "'");   
    }
} catch(error) {
    logger.error("JSONRequestThing.EncodeQueryToHTML(): Error Encoding String - " + error.message);
}

9. Click Save and Continue to save your changes.

GET Requests

For GET requests to a REST service, you will use the GetJSON service of the ContentLoaderFunctions Resource. This service takes parameters from the proxy information to how to handle SSL issues. All of the parameters are optional. Perform the following steps to create your ThingWorx service to make REST Get requests.

1. In the Services tab of the JSONRequestExample Thing, create a new service called JSONGetRequest.
   
   
2. The service will have the below properties as Input.
   
   

   Name	Base type	Required
   url	String	True
   header	JSON	False

3. In the Snippets section, filter and search for GetJSON.

4. Once you've found GetJSON under the ContentLoaderFunctions section, add it to the editor. You'll see all of the possible parameters for the request. In this example, we'll only set the url and header values.

5. Update the code snippet to include the parameters. Use the below code as a reference.

var params = {
    headers: header /* JSON */,
    url: url /* STRING */
};

// result: JSON
var result = Resources["ContentLoaderFunctions"].GetJSON(params);

6. Set the Output as JSON.

7. Click Save and Continue to save your changes.

This code will enable REST requests to be sent to an available web service. You will need to include the query string in the URL. In the provided sample, open the JSONRequestThing Thing and check out the JavaScript for the SearchMicrosoftBing service for a more complex example.

Note that you are setting the subscription key needed for a Microsoft Azure request and how to encode raw string input into a query string. Check out the Microsoft Azure documentation of the varying query strings that can be used.

POST/PUT Requests

POST and PUT requests are created similarly to GET requests. The methods in the ContentLoaderFunctions Resource is PostJSON and PutJSON. These services include a JSON based paramter titled content. This parameter will allow you to compose the body of the request.

Based on how the REST service is implemented, data will be in the content parameter or the headers parameter. See below for steps on creating a POST request.

1. In the Services tab of the JSONRequestExample Thing, create a new service called JSONPostRequest.
   
   
2. The service will have the below properties as parameters.
   
   

   Name	Base Type	Required
   url	String	True
   header	JSON	False
   body	JSON	False

3. In the Snippets section, filter and search for PostJSON.

4. Once you've found PostJSON under the ContentLoaderFunctions section, add it to the editor.

5. Update the parameter object to use the parameters for the service. Keep in mind, there are different ways this can be done. If the URL or the header will always be the same, then save these values as properties on the Thing and add parameters if the URL for this request will need them.

6. Test the new service with a running REST application or use both the GET and POST methods to setup your Azure Active Directory.

DELETE Requests

In ThingWorx, the DELETE method will be called similarly to the GET method. There will be a number of parameters that can be used and you will need to call the DELETE service of the ContentLoaderFunctions Resource. Follow to below instructions.

1. Duplicate the JSONGetRequest service you created earlier in order to get a head start on the new service.
   
   
2. When prompted, title this new service JSONDeleteRequest and save.
   
   
3. In the code area, use the snippet once again to add the delete service from ContentLoaderFunctions.
   
   
4. Update the JavaScript code to utilize the delete service.
   
   
5. Save, and you're done!

A simple test for calling this delete method via Azure, is using the REST service to delete an email template. The URI and parameters can be found in the Azure API.

Click here to view Part 2 of this guide.