Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

Handling a Web Service Request

Introduction

This document explains how a request is identified as being a web service request, how the runtime dispatches the request to a service processor that can perform any necessary pre- and post- processing of the request, and finally how this service processor identifies the service handler that will perform the actual business related logic.

This document gives a broad overview of the functionality, not a detailed description of each step. The different steps, and how to perform the setup / develop the necessary functions are described in separate documents.

What is a web service request

As such, there are no real differences between web service requests and common web requests.

The real difference is how the requests are handled and what they are used for.

In WebsydianExpress, the common web requests are handled in the following manner:

  1. The data sent with the request is parsed and made available in the WebInput variable of the EventHandler
  2. The EventHandler processes the input and calls a PageGenerator
  3. The PageGenerator generates the HTML page, which is finally returned to the browser

So a common web request is used in a browser context, where a users interacts with the application (typically pushes buttons/links) - this leads to requests being sent to the application, the application generates HTML, which is used to populate the browser.

A web service request is used in a different context. In many cases, there is no user (or browser) involved in creating the request. In most cases, a web service request contains a file, which is being handled by the application, which then generates another file, which forms the main part of the response returned to the client.

So the steps involved in WebsydianExpress' handling of a web service request is:

  1. A http request containing a file is received by the runtime.
  2. The file is saved to disk.
  3. The file is read by a program that is custom developed to handle this specific type of file.
  4. The same program creates a response file and saves it to the disk.
  5. The runtime creates the http-response based on the response file and returns it to the client.

Identifying a web service request

The first thing the runtime does when a http request is received is to identify whether it is a web service request or a common web request.

As mentioned, the requests have the same structure and can't be distinguished based on the content alone. On the site settings page in the administration interface, you can specify a URL-extension that will identify that a request is a web service request.

If the site is accessed by this URL:

http://www.websydian.com/site/basicsite

And "service" is specified as the URL-extension, all requests that is targeted to the URL:

http://www.websydian.com/site/basicsite/service

or any extensions of this URL will be handled as web service requests.

Service structure

The service structure is used to determine how a service request should be handled.

The structure describes which URL extensions of the service URL that targets different service processors, which criteria the service processors use to determine the service handler to call and the valid values of the criteria together with the service handler each value correspond to.

Find service processor

After the request has been identified as being a web service request, the next action the runtime performs is to select a service processor that can perform any pre- and post- processing on the received file and select the custom-developed service handler.

The service processor is identified based on the URL element specified in the service structure.

So for the URL:

http://www.websydian.com/site/basicsite/service/file

"file" is the part of the URL that will be used to identify the service processor to call.

The relation between the URL mask (e.g. "file") and the service processor to call is created on the service structure page in the administration interface.

The runtime identifies the service processor to call using the method described above. But before actually calling the program, a callback point is called. This means that it is possible to create your own functionality for deciding which service processor to call.

What is a service processor

All service processors perform three different tasks:

  1. Receive and preprocess data
  2. Identify and call handler
  3. Post process the response data and return them to the client.

There are three pre-defined service processors. These are delivered as part of the runtime:

  1. File service processor
  2. XML service processor (Not available in the iSeries version)
  3. Soap service processor (Not available in the iSeries version)

The file service processor saves the received data in a file, identifies and calls the handler, retrieves the file containing the response data and returns these data to the client.

The XML service processor receives the data, loads the data using an XML parser, identifies and calls the handler function, extracts the data from the response document and returns these data to the client.

The soap service processor receives the data, loads the data using an XML parser, extracts the body document from the Soap envelope, identifies and calls the handler, wraps the response in a soap envelope, extracts the data containing the soap document and returns it to the client.

Find service handler

For each URL element in the service structure, you must define one or more selection criteria on the service structure page in the administration interface (normally, only one selection criteria will be specified for each URL).

The selection criteria specifies how the service processor can identify the handler to call.

There are three 6 basic selection criteria that can be specified:

  1. URL
  2. Http-header
  3. Request parameter
  4. Soap Action
  5. Program
  6. XML top element name (Not available in the iSeries version).

For each selection criterion you can specify one or more service handlers together with a value for the selection criterion.

The service processor goes through the criteria that is defined for the URL. For each criterion, the corresponding value is extracted from the request, and it is checked whether a handler is defined for the value.

When the service processor has identified a service handler, the service handler is called.

What is a service handler

The handler performs the necessary business logic and returns information about the response to the service processor.

Each service handler is always custom developed for a specific purpose - as they contain the business dependent logic.

Return data to client

After the service handler has finished processing the request, the service processor returns the response data generated by the service handler and returns it to the client.

Diagram

The following diagram shows the different actions described above:

 

More information

Background: Service processors

Background: Selection criteria

Background: Service handlers

Background: Understanding the service structure

Background: Testing services