RESTful Web Services
Web Services
|
RESTful Web Services |
Web Services |
|
Web services provide a standard means of inter-operating between different software applications, running on a variety of platforms and/or frameworks.
PROIV RESTful Web Services allows PROIV functionality to be published as a web service and allows any web application to consume it in a controlled and secure way.
A PROIV RESTful Web Service is an implementation of the RESTful standard, supports XML and JSON formats. It is a lightweight protocol intended for exchanging structured information. The PROIV RESTful Web Services use HTTP and HTTPS to transfer the RESTful messages.
At the heart of PROIV’s RESTful Web Services are the RestfulRequestSSO and RestfulResponseSSO (Server Side Objects). These SSOs are utilized for RESTful Web Service calls, both incoming and outgoing to PROIV. They encapsulate the data structure which represents their HTTP/S counterparts in PROIV logic, providing the properties and methods required to use each SSO in either directional scenario from PROIV Developer.
The PROIV Control Panel is used to select and configure the RESTful web services that are to be exposed through HTTP/S, a network listener accepts the incoming HTTP/S requests and maps the HTTP/S request to a PROIV task and then collating the task's output into an HTTP/S response.
The PROIV RESTful task requires no parameters, instead this is done automatically as there is only one input parameter the RESTfulRequest and one output parameter the RESTfulResponse which cannot be modified by the developer. The input parameter is used to populate the contents of the RestfulRequestSSO before the task is started.
The RESTful task is restricted to only call a start function which is of the type ‘RESTful’ as this type of function has "SSO Params" defined to handle the RESTfulRequest and RESTfulResponse parameters. The RESTful Request and Response task parameters are converted to and from their corresponding SSO types upon execution and termination of the functions contained in the task.
The PROIV function triggered by the task queries the RESTfulRequest object, for information on the request, and sets the data in the RESTfulResponse object for the response. The RESTful PROIV task creates the output parameter from the structured data content that has been created within the RestfulResponseSSO during execution of the task.
The ‘RESTful’ type PROIV function can then access the contents of the RestfulRequestSSO and populate the RestfulResponseSSO through the properties and methods that are made available by the SSOs.
As the PROIV RESTful task completes its execution the RestfulResponseSSO is returned as its output parameter to the RESTful Web Service Listener through the Gateway. The RESTful Web Service Listener uses the information contained in the RestfulResponseSSO to encode an HTTP/S Response which is returned to the caller.
A RESTful service is consumed in PROIV logic using RESTful SSO objects. Use RestfulRequestSSO methods to construct the RESTful webservice request and RestfulResponseSSO methods to collect the generated response from the RESTful webservice. The function calls the methods (in PROIV logic) on the RestfulRequestSSO to set all the properties required for the request (header, body, URL) and calls the ‘send’ method. Use the ‘get’ methods on the RestfulResponseSSO to interrogate the contents of the generated response of the RESTful webservice.
StructuredDataObjectSSO can be utilized for setting more complex objects in the request and for collecting complex objects from the response.
The RESTful Request and Response are special types of SDOs (StructuredDataObject) which have a predetermined structure and additional methods relevant to their intended use.
The StructuredDataObject SSO defines an arbitrarily
complex object holding primitives (strings and numbers), objects and arrays
in any configuration and to any depth. At the simplest level, it holds
a collection of named primitive properties. At the top level, the properties
can be held either as an object or as an array. An object holds its properties
with names in no particular order. An array holds its properties by number
not by name. The first property in the array is at number one and not
at number zero. For more information, see Properties
and Methods of StructuredDataObject.
The RestfulRequestSSO represents a RESTful HTTP/S request. This SSO may be built from an incoming RESTful HTTP/S request or it may be built by PROIV logic and used to send a RESTful HTTP/S request. In addition to the header and body properties, this object will have other properties relevant to an HTTP/S request. This SSO has a collection of request parameters that have either been collected from an incoming HTTP/S request or set by the ‘set’ methods. These parameters are added to the URL if the SSO is used to send an HTTP/S request. For more information, see Properties and Methods of RestfulRequestSSO.
The RestfulResponseSSO represents a RESTful HTTP/S response. In addition to the header and body properties, this object will have other properties relevant to an HTTP/S response. This SSO may be built from the response to a RESTful HTTP/S request or it can be built by PROIV logic and used to send a RESTful HTTP/S response. It is the body object (a StructuredDataObject), that is converted to and from the HTTP/S response body. This conversion is done using the mime type defined for the HTTP/S request (typically JSON for RESTful Web Services). For more information, see Properties and Methods of RestfulResponseSSO.
Topic ID: 400029