Web Services

The Web Services data connector connects web services with VirtualSpace Fields and Tables as a web service consumer.

There are currently two supported web services types:

• RESTful (REpresentational State Transfer) using URL encoded parameters, and
• SOAP (Simple Object Access Protocol versions 1.1 and 1.2) using WSDL definitions.

The RESTful type is typically used for “simple” stateless services, whereas SOAP using WSDL is formal and more complex, also providing XML Schema validation of requests and replies.

The REST services are more unpredictable than SOAP services as the reply can vary both in format and contents in many cases. The positive about REST is that the services generally are simple, easy to use and fast to implement. It is not the necessarily the service architecture that makes it so, often it is just the fact that the services are not so complex.

Make sure that the Module project has the Web Services connector enabled in order to be able to define a new Web Service.

The folder used in the Module project is .

Web Services Editor

The Web Service Editor is divided into two areas; the left side is used for the request, i.e. for all parameters that makes up what is going to be sent to the remote party, and the right side for the remote reply that is received.

The top part of each area consists of a tree structure of the request and the reply respectively. The bottom part contains a property editor to edit the selected item in the tree of the same area.

REStful web service

A RESTful web service is created using the New Web Service Wizard, and currently only supports URL encoded parameters. This web service type is using the HTTP protocol and can be secured with SSL. The parameters are sent either in the request URL as e.g. http://url/path?p1=abc&p2=def or in the request body for larger data, using the HTTP methods GET, POST, PUT or DELETE.

Using the database analogy, the methods corresponds as Get = select/read, Post = update, Put = insert/create and Delete = delete.

The RESTful web services properties for a request are:

• URI:

Defines the web service URI including protocol, port specification (if required), but without the query (or parameters) part that starts with a question mark (?).

• Method:

Select the HTTP method to use, i.e. one of GET, POST, PUT or DELETE.

• Override method:

Specifies the method that overrides the request. Certain services (e.g. Google) uses a POST method overridden by a GET. In this case, specify GET as the overriding method. This technique is sometimes required to provide additional data that can be limited with e.g. the GET request.

• Encoding:

Specifies the encoding for the parameters, default is UTF-8.

• Read timeout:

Sets the maximum read timeout in milliseconds for the socket connection and is used to control the response time. The default value is 20000, i.e. 20 seconds. If a reply is not received within this time, the web service request fails with a timeout.

• NameSpace:

Sets the namespace to use for the input parameters. All input parameters must be located in this namespace (but the input and output namespaces can be different).

• Class:

Used for advanced processing, building and/or manipulation of the request. The class must implement the interface iizix.ws.api.IRESTfulRequestProcessor. It has a single method that is called prior to formatting the web service request, enabling e.g. fetching a Token that is used in the request to identify the requestor. See the JavaDoc of the interface for more information.

Creating a request

A free and public web service that gets the geolocation of an IP address is used in this chapter (see http://www.hostip.info/use.html for more information).

Fill in the request parameters as shown below:

In this case, the JSON reply format is chosen due to get_json.php (the path defines JSON for this service). The VirtualSpace start is also connected to the request.