Discovering how to access the Web Service

The Risaris SOA Gateway publishes the services available for the legacy data and business logic that it exposes using the Web Services Definition Language or WSDL.

This is an XML format document that describes the list of functions the Web Service implements, the input message that each function accepts and what it will return as output.

These WSDL documents are understood by the Web Services consumer, which can thus learn how to invoke the functions without any code or footprint on the Web Services consumer platform.

The following illustrates how the WSDL for a database file or legacy program can be obtained:

1. The Web Services client asks for the WSDL for the database resource or program containing the business logic they wish to access.

2. The WSDL file is returned giving the possible operations available (e.g. list, get, add, delete, etc) for a database resource process for a program containing business logic.

Accessing data on a database

3. After getting the WSDL, the user selects which operation they wish to execute. In this case, we have chosen the ‘list’ function which will return an XML document containing 0 or more records or rows from the file or table in the database for which the provided key data matches. The client software knows what keys are available as this information is published in the WSDL.

4. The Risaris SOA Gateway Apache module handles this request and passes the required information to the Risaris SOA Gateway engine.

5. The Risaris SOA Gateway engine passes this information to the independent data access module which issues proprietary access calls against the legacy database.

6. The legacy data access method communicates to the database and returns the data to the engine.

7. The results are constructed into a SOAP response by the engine.

8. Results are returned to the user in a standard SOAP response. The client software knows the format of this response as it will have been published in the WSDL.

Accessing the data using a URL
It is possible to access the data using a simple URL. The SOA Gateway also makes its resources available via the Representational State Transfer or REST model.

As the SOA Gateway uses the Apache Web server it is possible to accept and process any type of request HTTP request. The SOA Gateway will recognise a URL-based request by extending the range of parameters it accepts on the URL.

At the moment, a user requests access to the WSDL by using a GET request for the following URL:

http://<myhost>:<myport>/<SOA Gateway URI>?WSDL

It is possible to then provide additional instructions in a similar way and provide parameters to the request as follows:

http://<myhost>:<myport>/<SOA Gateway
URI>?<request>&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>

Where ‘p1’ to ‘pn’ are the field names for the request and ‘v1’ to ‘vn’ are their associated values.

This provides the following URL format that can be used to LIST or GET data from a resource by issuing a HTTP GET request with the following URLs:

http://<myhost>:<myport>/<SOA Gateway
URI>?LIST&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>
http://<myhost>:<myport>/<SOA Gateway
URI>?GET&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>

It will be possible to add or update a resource by issuing a HTTP POST or PUT request for the following URLs:

http://<myhost>:<myport>/<SOA Gateway
URI>?ADD&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>
http://<myhost>:<myport>/<SOA Gateway
URI>?UPDATE&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>

It will be possible to delete data from a resource using a HTTP DELETE request and the following URL:

http://<myhost>:<myport>/<SOA Gateway
URI>?DELETE&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>

...and as part of the section on invoking a 3GL or 4GL program containing business logic:

It is also possible to use the REST technology to invoke a Natural, PL/1 or COBOL program by using the following URL.

http://<myhost>:<myport>/<SOA Gateway
URI>?INVOKE&<p1>=<v1>&<p2>=<v2>&…&<pn>=<vn>

In practice, if the program will update something, the logic should use a POST or a PUT. If it’s an inquiry it should use a GET and if it deletes resources it should use a HTTP DELETE request. However, this is not strictly enforced and cannot be enforced by the SOA Gateway as it has no knowledge what the underlying program will do.

The response to all of the above requests will have the content type ‘TEXT/XML’ and will be a well formed XML document to be processed by the code that invokes the logic. When a response contains a BLOB, the message returned will be a multi-part message with the first part containing the first record in XML format. The second and subsequent parts will contain any BLOBs associated with that record, and the next part will contain the next XML record, and so on.

<< back