Retrieving Attributes from a REST Web Service

This section illustrates examples for the following tasks:

Sending requests and retrieving responses from a REST web service
Using Response parsing functions
Using test values

Example for Using Input Parameter

You can use the input parameter in the JavaScript format in the request body.

In this example, the endpoint is https://abc.example.com:8543/users/rest/asset/roles/user. This endpoint uses the POST method for a HTTP request and the following body content:

{
   "users": [
       {"id":"cn= user1,cn=system,cn=userapplication,cn=app1,ou=example,o=com"}
   ]
}

To change the body content to JavaScript and provide cn from defined input parameters, perform the following steps:

In Step1: Provide input parameters, specify {P1} as input parameter with parameter value cn.

Add the test values for {P1} as user and system.

In step 2: Configure Request and Response, change the request body message as follows:

function main({P1}) {
var cnValues = "cn=" + {P1}[0] + ",cn=" + {P1}[1]+ ",cn=userapplication,cn=app1,ou=example,o=com";
var json = {
                "users": [
                  {"id":cnValues}
                ]
                };
return json;
}

You can provide multiple test values to a parameter {P1} and use the values as array in the JavaScript function for Resource/ API Path and Body.

NOTE:If {P1} has only one input value, Access Manager interprets {P1} in JavaScript as a string and not as an array. Hence, for a single input value use {P1} instead of using {P1}[0].

If multiple values are available for {P1}, JavaScript returns all elements that are separated by a comma (,). For example, test1,test2. Whereas, {P1} in plain text returns only the first value. For example, test1.

Response Parsing Functions

When a REST web service receives a request, it returns a response. Access Manager adds the response body as the Response_As_Is parameter under Response Parameters. This parameter gets added by default. This function is used to get the specific data from a response. Most of the REST web services return responses in the JSON format. The response can be sent in any other format, such as xml and plain text. Access Manager includes the response parsing functions for JSON and XML. For any response that uses other formats, use the advanced JavaScript option.

You can add test values and click Test to test the result of the request.

The following example explains the response parsing functions:

Sample response returned from REST endpoint (Response_As_Is):

The REST web server returns the data of all students in an array of JSON format as mentioned in the following sample response:

{
  "students": [
    {
      "name": "xyz",
      "id": 1234,
      "subjects": [
        "English", "French"
      ],
      "department": "dept1",
      "branch": "IND"
    },

    {
      "name": "abc",
      "id": 124,
      "subjects": [
        "French"
      ],
      "department": "dept2",
      "branch": "IND"
    },

     { "name": "pqr",
      "id": 223,
      "subjects": [
        "Spanish"    
    ],
      "department": "Dept1",
      "branch": "IND"
    }]
}

This sample response is used as an example for JSON Parse, JSON Parse with Match Conditions, JSON Parse with Match Regex, and Advanced: Javascript.

The following is the list of functions:

JSON Parse: Parse the data with JSON Parse() to retrieve the data from JSON. This modification function uses the JavaScript’s JSON.Parse function. On selecting this response parsing function, you must specify JSON Parse String.

Use the following inputs to retrieve specific attributes. You can provide the JSON Parse String value with standard JavaScript’s JSON.Parse function.

JSON Parse String (input value)	Scenario	Response Parameter	Test Result
students[0].name	The value of the name attribute is retrieved from the first JSON in the response. This value must be mapped to param1.	param1	param1=xyz The output is xyz as the value of the name attribute is xyz in the first array of JSON. The specified Response Parameter is param1, so the test result displays it as the parameter in response.
students[1].name	The value of the name attribute is retrieved from the second JSON in the response. This value must be mapped to name.	name	name=abc Here, the output is abc because the value of the name attribute is abc in the second array of JSON. The specified Response Parameter is name, so the test result displays it as the parameter in response.
students[0].subjects[0]	In this scenario, we are retrieving the first value of the subjects attribute from the first JSON of the response.	param1	param1=English Here, the output is English because the first value of the subjects attribute in the first array of JSON is English. The value for the subjects attribute is in an array format, so specifying subjects[0] in JSON Parsing String retrieves the first value in the array.
students[0].subjects[1]	The second value of the subjects attribute is retrieved from the first JSON of the response. This value must map to param1.	param1	param1=French The output for param1 is French as it is the second value of the subjects attribute in the first array of JSON. The value for the subjects attribute is in an array format, so specifying subjects[1] in JSON Parsing String retrieves the second value in the array.
students[0]	The values of students is retrieved from the first JSON of the response. These values must map with name, id and param1 in the same order.	name id param1	name=xyz id=1234 param1=<no value gets displayed> The output is based on the number of values available for the students attribute. In the first array of JSON, only two values are available for students. The third parameter param1 is not mapped to any value. You can change the order of Response Parameter by using up and down arrow. The values are mapped based on the order specified for Response Parameter. For example, if the order of Response Parameter is as follows: name param1 id The output in the Results window displays: name=xyz param1=<no value gets displayed> id=1234

JSON Parse with Match Conditions: This function finds an array from the response and then apply match conditions on the array elements to find the attribute that matches all the conditions. The following table includes the sample input value and its result when the data of a student whose department is dept1 is retrieved:

Scenario: The value of students attribute that includes the attribute name department with value dept1 is retrieved.

JSON Array Parse String (input value)	Response Parameter	Test Result
students Match Conditions Name: department Value: dept1	name id param1	name=xyz id=1234 param1=<no value gets displayed> When the condition is applied on the students JSON of array, the name parameter matches with name attribute of the response and the id parameter matches with the id attribute of the response. However, no param1 attribute is available in the response. Therefore, no value gets mapped to param1.

JSON Array Parse String (input value)

Response Parameter

Test Result

students

Match Conditions

Name: department

Value: dept1

name
id
param1

name=xyz
id=1234
param1=<no value gets displayed>

When the condition is applied on the students JSON of array, the name parameter matches with name attribute of the response and the id parameter matches with the id attribute of the response. However, no param1 attribute is available in the response. Therefore, no value gets mapped to param1.

JSON parse with Match Regex: This is the same as JSON Parse with Match Conditions except that you can specify regex in the match condition. The following are examples of using regex:

Scenario: Attribute values is retrieved from the students JSON of array that includes the attribute name as department and the value as dept1. The value dept1 is case-insensitive.

JSON Array Parse String (input value)	Response Parameter	Test Result
students Match Regex: Name: department Regex: /dept1/i	name id	name={ "name": "xyz", "id": 1234, "subjects": [ "English", "French" ], "department": "dept1", "branch": "IND" } id={ "name": "pqr", "id": 223, "subjects": [ "Spanish" ], "department": "Dept1", "branch": "IND" } The full JSON response is displayed for name and id as the specified regex condition is true for both dept1 and Dept1. As two matches are available for the specified condition, the parameters are mapped to two separate JSONs.

JSON Array Parse String (input value)

Response Parameter

Test Result

students

Match Regex:

Name: department

Regex: /dept1/i

name
id

name={ "name": "xyz", "id": 1234, "subjects": [ "English", "French" ], "department": "dept1", "branch": "IND" }
id={ "name": "pqr", "id": 223, "subjects": [ "Spanish" ], "department": "Dept1", "branch": "IND" }

The full JSON response is displayed for name and id as the specified regex condition is true for both dept1 and Dept1. As two matches are available for the specified condition, the parameters are mapped to two separate JSONs.

Scenario: Attribute values of the attributes are retrieved from the students JSON of array that includes the attribute name as department and the value must be only dept1.

JSON Array Parse String (input value)	Response Parameters	Test Result
Match Regex: Name: department Regex: /dept1/	name id	name=xyz id=1234 The exact match for both response parameters are displayed as one match is available for name and one match for id in the response that meets the mentioned condition.

Advanced JavaScript: Use this if you require any custom JavaScript to parse any kind of data returned by a web service. If a function is an array, the order of the parameters under Response Parameters is significant. However, the order is not significant for JSON as it maps to the same name. The following is an example script for parsing the response with Advanced: Javascript:

Scenario: A JavaScript is written to retrieve the attribute and customize it based on the requirement. For adding the email parameter value, {P1} as input parameter is specified. A test value for {P1} as example is added.

Script	Response Parameters	Test result
function main(Response_As_Is, {P1}) { var jsonRes = JSON.parse(Response_As_Is); var p1Val = ""; if({P1} instanceof Array) { var arrElem = {P1}[1]; if(arrElem != undefined) { p1Val = arrElem; } } else { p1Val = {P1}; } var arrResult = []; for(i = 0;i< jsonRes["students"].length -1; i ++) { var jsonTemp = {}; jsonTemp.id = jsonRes["students"][i]["id"]; jsonTemp.mail = jsonRes["students"][i]["students"] + p1Val; arrResult.push(jsonTemp); } return arrResult; }	Param1 Param2	Param1 : { "id": 123, "mail": " xyz@example.com" } Param2: { "id": 124, "mail": "abc@example.com" } The response from the REST web service is modified to return the array of students JSON that contains id and mail. The mail attribute is modified with the input parameter values. In this scenario, the result of the JavaScript is an array of JSONs. Hence, the response parameters param1 and param2 are mapped with each JSON (in the same order). You can change the order of Response Parameters by using up and down arrow. The values are mapped based on the order you specify. For example, the order of Response Parameters is as follows: param2 param1 The output in the Results window displays: param2 : {"id": 1234, "mail": " xyz@example.com" } param1: {id": 124,"mail": "abc@example.com" }

Script

Response Parameters

Test result

function main(Response_As_Is, {P1}) {
  var jsonRes = JSON.parse(Response_As_Is);
  var p1Val = "";
  if({P1} instanceof Array) {
    var arrElem = {P1}[1];
    if(arrElem != undefined) {
       p1Val = arrElem;
    }
  } else {
     p1Val = {P1};
  }
  var arrResult = [];
  for(i = 0;i< jsonRes["students"].length -1; i ++) {
     var jsonTemp = {}; jsonTemp.id = jsonRes["students"][i]["id"];
     jsonTemp.mail = jsonRes["students"][i]["students"] + p1Val;
    arrResult.push(jsonTemp);
  }
  return arrResult;
}

Param1

Param2

Param1 : {
  "id": 123,
  "mail": " xyz@example.com"
}

Param2: {
  "id": 124,
  "mail": "abc@example.com"
}

The response from the REST web service is modified to return the array of students JSON that contains id and mail. The mail attribute is modified with the input parameter values. In this scenario, the result of the JavaScript is an array of JSONs. Hence, the response parameters param1 and param2 are mapped with each JSON (in the same order).

You can change the order of Response Parameters by using up and down arrow. The values are mapped based on the order you specify. For example, the order of Response Parameters is as follows:

param2
param1

The output in the Results window displays:

param2 : {"id": 1234, "mail": "  xyz@example.com"
}

param1: {id": 124,"mail": "abc@example.com"
}

XML Parse with XPath: You can use this if the web service response is in the form of XML, and you require to provide the XPath to extract the attribute from the xml based on the standard XPath format.

Sample Response in xml format(Response_As_Is): The following is a sample response that is sent by a REST web service:

<bookstore>
<book>
<title lang="en">
Harry Potter
</title>
<price>
29.99
</price>
</book>
<book>
<title lang="sp">
Learning XML
</title>
<price>
40
</price>
</book>
<book>
<title lang="dt">
ABCD
</title>
<price>
100
</price>
</book>
</bookstore>

XPath	Scenario	Response Parameter	Test Result
/bookstore/book/title/text()	All values are retrieved from title nodes in the xml response.	test	test=[Harry Potter, Learning XML, ABCD]
/bookstore/book[1]/title/text()	The value is retrieved from title nodes within the first book node in the xml response.	test	test=Harry Potter
/bookstore/book[1]/title	The complete title node is retrieved within the first book node in the xml response.	test	<title lang="en"> Harry Potter </title>

Response Parameters: When you select a response parsing function, you require to specify an output parameter under Response Parameters to get the required parameter mapped to the output parameter. You can use the parameter name specified under Response Parameters while configuring virtual attributes.