HANDLING RESTful DATA IN PROIV LOGIC |
DEVELOPER |
 |
RESTful Request Data
Request Query Parameters in the URL
A RESTful Request can contain query parameters (name/value pair) and the simplest manner in which parameters can be defined is by appending them to the end of the URL.
http://MyServer:port/Rwsurl?Name=Value&Name2=Value2
The URL is followed by a question mark and you then append name=value pairs separated by an ampersand. Shown below is how you would set up the URL in PROIV logic to send a RESTful Request ("request" is the RestfulRequestSSO).
$pValue = "http://MyServer:port/Rwsurl?Name=Value&Name2=Value2"
request.setURL(paramMap)
When PROIV decodes an incoming RESTful Request to create a RestfulRequestSSO it collects any query parameters that have been added to the URL and puts then in a "parameters" object inside the RestfulRequestSSO. Shown below is how you would collect the values in PROIV logic when receiving a RESTful Request.
$pName = "Name"
$value = request.getParameter(paramMap)
$pName = "Name2"
$value2 = request.getParameter(paramMap)
The downside to URL parameters is that as they form part of the URL they are visible to all and sundry in plain text as the call is routed to its destination.
Request Query Parameters in the Body
Just as you can put query parameters in the HTTP Request header you can also put them in the HTTP Request Body. To do so, you need a Request Body. The GET HTTP method does not have a body and so can not be used for these type of parameters.
To add query parameters in a request body in a RESTful Request to send using the PROIV RestfulRequestSSO you must first set the "Content-Type" header parameter to "application/x-www-form-urlencoded" and then put the parameters into the "stringBody" object as name value pairs seperated by an ampersand (just like the URL query parameters above).
$pName = "Content-Type"
$pValue = "application/x-www-form-urlencoded"
request.setHdrParameter(paramMap)
$pName = "stringBody"
$pValue = “Name=Value&Name2=Value2"
request.setString(paramMap)
When PROIV decodes an incoming RESTful Request to create a RestfulRequestSSO if the Request "Content-Type" header is set to "application/x-www-form-urlencoded" then any URL encoded parameters that are found in the body are collected and added to the parameters object. You would collect the values in PROIV logic when receiving a RESTful Request in exactly the same way as for the URL query parameters (see above).
$pName = "Name"
$value = request.getParameter(paramMap)
$pName = "Name2"
$value2 = request.getParameter(paramMap)
Request Header Parameters
In an HTTP request there are a number of default header parameters as requests should conform to the HTTP specification, these are User-Agent, Content-Type & Accept-Language. Additionally, it is permissible to include any others which a particular implementation requires, therefore it is common for a RESTful web service to include additional parameters in the header.
In order to put header parameters into a RESTful Request to send using the PROIV RestfulRequestSSO you use the setHdrParameter method.
$pName = "artist"
$pValue = $artist
request.setHdrParameter(paramMap)
$pName = "title"
$pValue = $title
request.setHdrParameter(paramMap)
To collect the values of the header parameters from an incoming RESTful Request from the PROIV RestfulRequestSSO you use the getHdrParamaeter method.
$pName = "artist"
$artist = request.getHdrParameter(paramMap)
$pName = "title"
$title = request.getHdrParameter(paramMap)
Request JSON Body
When there is a requirement to send more complex or larger data the Request query parameters or header parameters are not that useful, instead the data is put in the Request Body in the form of either JSON or XML. To add JSON content in the Request body the "Content-Type" needs to be set to "application/json". This tells the PROIV Request builder to convert the RestfulRequestSSO body object to a JSON string and put it in the Request body. You define the body object using the various set methods available to the RestfulRequestSSO. Note that the body object can be defined using a simple JSON string (the setFromJSON method) or built up into a complex object structure containing many levels.
Here is how you would set up a very simple JSON Body.
$pName = "Content-Type"
$pValue = "application/json"
request.setHdrParameter(paramMap)
$pName = "/body"
$pValue = '{"artist":"' + $artist + '","title":"' + $title + '"}'
request.setFromJSON(paramMap)
The above would have the effect of setting two name value pairs in the body, artist and title, and is equivalent to:
$pName = "Content-Type"
$pValue = "application/json"
request.setHdrParameter(paramMap)
$pName = "/body/artist"
$pValue = $artist
request.setString(paramMap))
$pName = "/body/title"
$pValue = $title
request.setString(paramMap))
When PROIV decodes an incoming RESTful Request to create a RestfulRequestSSO if the "Content-Type" header is "application/json" then the Request body is decoded and converted into the body object. You would then access the JSON data from the Request as shown below:
$pName = "/body/artist"
$artist = request.getString(paramMap)
$pName = "/body/title"
$title = request.getString(paramMap)
Request XML Body
As well as JSON PROIV also allows you to define the Request body as XML. If the "Content-Type" is set to "application/xml", then any data in the body object of the RestfulRequestSSO will be converted into an XML string and put in the Request body.
The logic below would set up an XML body in the Request of "<myxml><artist>Bogart</artist><title>Casablanca</title></myxml>".
$pName = "Content-Type"
$pValue = "application/xml"
request.setHeader(setParam)
$pName = "/body/myxml/artist"
$pValue = "Bogart"
request.setString(paramMap))
$pName = "/body/myxml/title"
$pValue = "Casblanca"
request.setString(paramMap))
When PROIV decodes an incoming RESTful Request to create a RestfulRequestSSO if the "Content-Type" header is "application/xml" then the Request body is decoded and converted into the body object. Assuming the XML was "<myxml><artist>Bogart</artist><title>Casablanca</title></myxml>", you would then access the XML data from the Request as shown below:
$pName = "/body/myxml/artist"
$artist = request.getString(paramMap)
$pName = "/body/myxml/title"
$title = request.getString(paramMap)
Request Raw Text Body
You can put any text data in a Request body. To do this you must set the "Content-Type" header to be anything except "application/json" and "application/xml", using "text/plain" is very common. Then put the text in the "stringBody" property of the RestfulRequestSSO. When PROIV uses this RestfulRequestSSO to send a Request the "stringBody" text is put in the Request body unchanged.
Here is how you would set up a text body in a Request.
$pName = "Content-Type"
$pValue = "text/plain"
request.setHeader(paramMap)
$pName = "/stringBody"
$pValue = "Some text data"
request.setString(paramMap)
Note that any content type that is not "application/json" or "application/xml" will use the stringBody as the Request body and not the body object.
When PROIV decodes an incoming RESTful Request to create a RestfulRequestSSO if the "Content-Type" header is not "application/json" or "application/xml" then the Request body is only put in the RestfulRequestSSO stringBody object and the RestfulRequestSSO body object will be empty.
RESTful Response Data
Response Header Parameters
The RESTful Response can have header parameters just like the Request and in order to put header parameters into a RESTful Response sent using the PROIV RestfulResponseSSO you use the setHdrParameter method.
$pName = "artist"
$pValue = $artist
response.setHdrParameter(paramMap)
$pName = "title"
$pValue = $title
response.setHdrParameter(paramMap)
To collect the values of the header parameters from an incoming RESTful Response from the PROIV RestfulResponseSSO you use the getHdrParamaeter method.
$pName = "artist"
$artist = response.getHdrParameter(paramMap)
$pName = "title"
$title = response.getHdrParameter(paramMap)
Response JSON Body
The Response body is usually used to return the result of a RESTful Request and this is often as JSON or XML. To add JSON results in the Response body the "Content-Type" needs to be set to "application/json". This tells the PROIV Response builder to convert the RestfulResponseSSO body object to a JSON string and put it in the Response body. Note that the body object can be defined using a simple JSON string (the setFromJSON method) or built up into a complex object structure containing many levels.
Here is how you would set up a very simple JSON Body.
$pName = "Content-Type"
$pValue = "application/json"
response.setHdrParameter(paramMap)
$pName = "/body"
$pValue = '{"artist":"' + $artist + '","title":"' + $title + '"}'
response.setFromJSON(paramMap)
The above would have the effect of setting two name value pairs in the body, artist and title, and is equivalent to:
$pName = "Content-Type"
$pValue = "application/json"
response.setHdrParameter(paramMap)
$pName = "/body/artist"
$pValue = $artist
response.setString(paramMap))
$pName = "/body/title"
$pValue = $title
response.setString(paramMap))
When PROIV decodes an incoming RESTful Response to create a RestfulResponseSSO if the "Content-Type" header is "application/json" then the Response body is decoded and converted into the body object. You would then access the JSON data from the Response as shown below:
$pName = "/body/artist"
$artist = response.getString(paramMap)
$pName = "/body/title"
$title = response.getString(paramMap)
Response XML Body
As well as JSON PROIV also allows you to define the Response body as XML. If the "Content-Type" is set to "application/xml", then any data in the body object of the RestfulResponseSSO will be converted into an XML string and put in the Response body.
The logic below would set up an XML body in the Response of "<myxml><artist>Bogart</artist><title>Casablanca</title></myxml>".
$pName = "Content-Type"
$pValue = "application/xml"
response.setHeader(setParam)
$pName = "/body/myxml/artist"
$pValue = "Bogart"
response.setString(paramMap))
$pName = "/body/myxml/title"
$pValue = "Casblanca"
response.setString(paramMap))
When PROIV decodes an incoming RESTful Response to create a RestfulResponseSSO if the "Content-Type" header is "application/xml" then the Response body is decoded and converted into the body object. Assuming the XML was "<myxml><artist>Bogart</artist><title>Casablanca</title></myxml>", you would then access the XML data from the Response as shown below:
$pName = "/body/myxml/artist"
$artist = response.getString(paramMap)
$pName = "/body/myxml/title"
$title = response.getString(paramMap)
Response Raw Text Body
You can put any text data in a Response body. To do this you must set the "Content-Type" header to be anything except "application/json" and "application/xml", using "text/plain" is very common. Then put the text in the "stringBody" property of the RestfulResponseSSO. When PROIV uses this RestfulResponseSSO to send a Response the "stringBody" text is put in the Response body unchanged.
Here is how you would set up a text body in a Response.
$pName = "Content-Type"
$pValue = "text/plain"
response.setHeader(paramMap)
$pName = "/stringBody"
$pValue = "Some text data"
response.setString(paramMap)
Note that any content type that is not "application/json" or "application/xml" will use the stringBody as the Response body and not the body object.
When PROIV decodes an incoming RESTful Response to create a RestfulResponseSSO if the "Content-Type" header is not "application/json" or "application/xml" then the Response body is only put in the RestfulResponseSSO stringBody object and the RestfulResponseSSO body object will be empty.
Topic ID: 500686