Querying REST Service Results

The RESTServiceWrapper object can be used to query results from a REST service without the need to display the REST Grid widget on a custom form. This topic describes the object and the methods that perform this function, and provides example JavaScript code.

Both JSON data and plain old XML (POX) data can be accepted. For JSON data, the results of the REST service are evaluated as a JavaScript object.

Note: See REST Grid Widget for widget information.

RESTServiceWrapper

This object defines the REST service to query; provides authentication and proxy information, if applicable; and specifies whether JSON data is returned from the REST service. Its parameters are described in the following table.

Name	Type	Description
`url`	String	Required. Base URL of the service to query.
`username`	String	User name to access the REST service, if authentication is required.
`password`	String	Password to access the REST service, if authentication is required.
`useProxy`	Boolean	Whether to access the REST service through the SBM proxy. The default value is false.
`jsonResponse`	Boolean	Whether the results of the REST service are JSON data. (If this parameter is not supplied, it is considered to be true.)

get

This function returns data from a REST service. Its parameters are described in the following table.

Name	Type	Description
`path`	String	The service path on which to do a GET .
`queryString`	String	The query string with which to do a GET.
`callback`	Function	The JavaScript function to invoke when the REST data is returned. The first parameter will be the result data if `success` is true; otherwise, it will be the failure message. The second parameter is the user-defined `tag` as passed to the `get` call.
`tag`	Depends on parameter	A user-defined parameter to be passed to the callback along with the REST data.
`customHeaders`	Array	An array of two-element arrays containing the name and value of each custom header to pass to the callback.

post

This function posts data returned from a REST service to the custom form. Its parameters are described in the following table.

Name	Type	Description
`path`	String	The service path on which to do a POST.
`queryString`	String	The query string on which to do a POST.
`callback`	Function	The JavaScript function to invoke when the REST data is posted. The first parameter will be the result data if `success` is true; otherwise, it will be the failure message. The second parameter is the user-defined `tag` as passed to the `post` call.
`tag`	Depends on parameter	A user-defined parameter to be passed to the callback along with the REST data.
`customHeaders`	Array	An array of two-element arrays containing the name and value of each custom header to pass to the callback.

Example

The following example uses the RESTServiceWrapper object to query the Yahoo geocode REST service and display the results. The search term and the ID of the table element are passed to the loadData() function.

In this example, the user selects an option and then clicks a button on a custom form. The button is configured to call the JavaScript function specified in an HTML/JavaScript widget on the form. If the JSON option is selected, the results are displayed as an HTML table; otherwise, the results are displayed as a string of unformatted XML.

Note: For a process app that demonstrates this functionality, go to solution S138336 in the Knowledgebase at serena.com and download the RESTServiceWrapper Example.msd file.

var displayParams = ["latitude", "longitude", "line2"];
function loadData(query, tableID)
{
         var url = "http://where.yahooapis.com";
         var path = "/geocode";
         var queryString = "q=" + query;

         var jsonResponse = (GetFieldValue("Response Type") == "JSON");
         if (jsonResponse) queryString += "&flags=J";

         var wrapper = new RESTServiceWrapper(url, null, null, false, 
         →jsonResponse); 
              
         var customHeaders;
         //customHeaders = [["CustomX", "ValueX"], ["CustomY"],];
         wrapper.get(path, queryString, displayData, tableID, 
         →customHeaders);
}

function displayData(results, tag, success)
{
         if (!success)
         {
                 alert('Request failed with status: ' + results);
                 return;
         }

         var jsonResponse = (GetFieldValue("Response Type") =="JSON");

         var table = document.getElementById(tag);
         // Clear
         for (var index = table.rows.length - 1; index >= 0; index--)
         {
                 table.deleteRow(index);
         }

         if (jsonResponse)
         {  
                 var resultSet = results["ResultSet"];
                 var length = resultSet["Found"];
                 var results = resultSet["Results"];

                 // Header
                 var row = table.insertRow(table.rows.length);
                 for (var jndex = 0; jndex < displayParams.length; jndex++)
         {
                      var cell = row.insertCell(row.cells.length);
                      cell.innerHTML = displayParams[jndex];
         }

                // Data
                for (var index = 0; index < length; index++)
                {
                      var result = results[index];

                      var row = table.insertRow(table.rows.length);
                      for (var jndex = 0; jndex < displayParams.length; 
                      →jndex++)
                      {
                          var cell = row.insertCell(row.cells.length);
                          cell.innerHTML = result[displayParams[jndex]];
                      }
               }
          }
          else
          {
                //Just output response
                var row = table.insertRow(table.rows.length);
                var cell = row.insertCell(row.cells.length);
                var text = document.createTextNode(results);
                cell.appendChild(text);
          }
}