Web services response template pattern: a specification

The Web services response template pattern offers service providers and clients more control and flexibility over request response invocations in a heterogeneous environment. WSRT lets the client control the service result and optimize data flow to specifications. At the same time, it allows service providers to develop the interfaces they provide without breaking existing clients. We’ll examine the WSRT pattern specification and the solutions it offers to improve service interfaces.

Share:

Eoin Lane, Senior Solution Engineer, IBM, Software Group

Dr. Eoin Lane, Senior Solution Engineer, is the lead for harvesting and developing of application pattern from key IBM SOA engagements and driving those patterns through IBM pattern governance process to accelerate adoption. Eoin also specializes in Model Driven Development (MDD), asset based development and Reusable Asset Specification (RAS) to facilitate SOA development.



10 February 2006

Also available in Chinese

Context

Web services have quickly become the norm for request response invocations in a heterogeneous environment. However, the verbose ASCII nature of these invocations impacts performance, leading architects to consider alternative solutions.

We'll take a close look at some of the problems Web services providers may face when dealing with multiple clients, and how to solve them using the WS response template pattern.


Problem

Service interfaces often present the following problems:

  • Service interfaces are typically coarse-grained but the client often wants more control over their granularity of access.
  • Service providers need to evolve the interfaces they provide without breaking existing clients.

Web services providers have a common problem when dealing with multiple clients: WSDL prescribes an exact interface for data types, messages, and operations that implicitly restricts clients to a usage pattern that is not necessarily appropriate. Service providers must choose the WSDL they expose, even though clients know the most efficient interface for their usage patterns.

Service provides must choose whether to provide multiple interfaces for multiple clients -- which is hard to develop and maintain -- or to provide a single 'one-size-fits-all' compromise interface.

Take as an example a vehicle data service in an automotive company. The create, read, update, and delete (CRUD) operations of this vehicle service need to be accessed by multiple applications, as the majority of applications in an automotive company will need to access vehicle information. However, each of these applications will have different requirements on the subset of vehicle data that they require. A warranty application will require a different subset of vehicle information from a customer service application. The provider of this data service is now faced with the dilemma: provide multiple interfaces with different levels of granularity of vehicle data, or to provide a catch-all interface that satisfies no one.

How can clients be more clearly decoupled from using the contract specified by a service provider?


Forces

Several forces are in play when building a Web service. An architect needs to be able to:

  • build on existing Web service standards
  • increase flexibility, granularity, and maintainability of Web service interfaces
  • customize service results and optimize the data flow between client and server
  • enable consumers and providers to develop against abstract data and service models rather than directly to prescribed interfaces.

Solution

The WS response template pattern (WSRT) allows clients to program toward abstract data and service models, rather than directly to WSDL-specified interfaces, and then specify a subset of information in that model to be returned as the result of service invocation. In addition to defining the structure of the response, clients can supply additional search parameters in order to qualify which objects will actually be returned. This gives the client a high degree of control over the service result and lets him optimize data flow to his own specifications. In addition, it allows service providers to develop the interfaces they provide without necessarily breaking existing clients.

The WS response template pattern makes the service interface more flexible. The operation signature is changed to accept, in addition to a key, a request template, and then returns a response template. The request template is a loosely-typed graph where all the attributes are optional; the response template is strongly typed and all the attributes are optional.

For example, a service interface could have the following operation:

getValueObject(key:Key):ValueObject

After applying the pattern the operation signature would change as follows:

getValueObject(key:Key,requestTemplate:RequestTemplate):ResponseTemplate

The RequestTemplate and the ResponseTemplate are based on the original value object with the following modifications:

  • The RequestTemplate is loosely typed and all the attributes are optional. The RequestTemplate contains a description of what should be in the ResponseTemplate
  • The ResponseTemplate is strongly typed and all the attributes are optional. The ResponseTemplate contain the information from the orginal ValueObject but in a form dictated by the requester given in the RequestTemplate.

The UML 2.0 Profile for Software Services provides a common language for describing services, one of which covers activities through the development lifecycle and also provides views to different stakeholders.
The UML profile for software services enables the modeling of services, Service-Oriented Architecture (SOA), and service-oriented solutions. The profile has been implemented in IBM Rational® Sofware Architect, used successfully in developing models of complex customer scenarios, and helps educate people about the concerns relevant to developing service-oriented solutions (see Resources.)

In a model-driven development solution of this pattern, the WS response template pattern follows a UML service design model, as in Figure 1.

This is a UML class diagram where the input is an interface and class graph that represents the data model. This services model could have the UML service profile applied (see the Sidebar.) The output is a services model that is WS response template-aware.

This WS response template-aware service model could then be transformed to WSDL and XSD using a UML-to-SDL and UML-to-XSD transformation.

In a final step the flexible WSDL can be used to create implementation stubs and skeleton code using, for example, the WSDL-to-Java generation.

Figure 1. WS response template solution outline
WS response template solution outline

Class Diagram

Figure 2 shows a UML service model where the interface of the service contains a number of CRUD-like operations. The data object in these CRUD operations, ideally for this pattern, is a composite value object data object. This means the data value object can be either a leaf data value object or an aggregative data value object that contains other value objects.

Since the data value object can contain an aggregation of other data value objects -- such as a bank account data object with multiple transaction data objects -- an implementation of the WS response template pattern should support filtering of a child aggregate data value objects, based on some kind of filtering criteria. For example, if we only want to see the past week's bank account transitions, the child aggregate data value object would have a filter for the date.

Figure 2. WS respose template class diagram
WS respose template class diagram

Sequence diagram

Figure 3 shows the sequence diagram for the WS response template pattern.

Figure 3. WS respose template sequence diagram
WS respose template sequence diagram

Consider the sequence diagram:

  • Using the provided WS response template-aware WSDL, the client invokes the service. The requester then invokes the WS response template implementation with a key and a request template.
  • The key uniquely identifies the value object required.
  • The request template tells the service implementation what (disconnected) sub set of data object graph is required in the response.
  • The service implementation queries the provider using the key and gets the corresponding data object associated with that key.
  • A runtime component, called the navigator, is now invoked. The navigator takes a request template and a value object as input and returns and response template.
  • The response template contains a type-safe subset of the value object information graph requested by the user in the request template. The response template is returned to the requester.

Participants

The following are the related participants and their associated actions:

  • Information model/service graph: Data object model and service Mmodel that defines what information a service will provide (and the CRUD like operations that can request it).
  • Request template XSD: defines the possible formats of a request template. This request template defines a loosely typed structure of the Information Model.where all of the elements are optional and represents the possibilties of requests that can be send by the requester to the provider.
  • Request template - XML: An instance of the request template XSD send on the wire as part of the request
  • Response template XSD: defines the possible formats of a response template. The response template is typically a strongly typed structure of the Information Model.where all of the elements are optional and represents the possibilties of responses that can be send by the provider to the requester.
  • Response template XSD: An instance of the response template XSD send on the wire as part of the request
  • Navigator: The WS response template provider side engine used to parses the incoming request template and creates a response template as a result, pulling information from the Web services result object graph.

Consequences

In performing this, one has to be aware of the potential consequences, such as:

  • Customized result: Clients of a WS response template service can adjust the results they receive from service invocation: unwanted data will not be sent by the server, nor will any placeholder data be received on the client side (not even with nil or empty values).
  • Optimized data flow: The service invocation consists of a data exchange between two parts (traditionally two computers). The Web services templates solution must minimize the data flow between those two parts. Attention must be paid to the expression of the data flow in order to minimize the weight of this. For example, when using XML, pay attention to namespace declarations, element prefixes, hierarchical structure of the data flow, etc
  • Optimization of the service implementation: WS response templates solution will allow the service provider developer to optimize the process by only invoking methods or retrieving data that will be needed to construct the result as defined by the client.
  • Standards based: The WS response templates is designed in conformity with the Web Services standards:
    • SOAP communication protocol: Web services templates must be implemented using SOAP. We will use JAX-RPC compliant engine as the platform of choice for the service implementation (server-side). Whereas this implementation exists primarily for HTTP transport protocol, this does not mean that the Web Services Templates must only be bound to a specific transport protocol (but can be used with other such as JMS ?)
    • Services will be defined using WSDL, and XML schema to define the formats of the exchanged objects
    • The operations have a document style and a literal usage (Doc/literal), for WS-I compliance
  • Parameterized navigation path: The navigation path against an information model hierarchy can define extra parameters to filter a particular relationship. Also, this parameterized path could be repeated in the same service invocation, to extend the potential of the service (especially for the parameterized path).
    • Note: This does not mean that the Web service operation can be invoked multiple times in the same call. Only that the returned object graph can be controlled to a greater degree than in normal Web Services design patterns.
  • Level of granularity for services: The WS response templates patterns will reduce the granularity of Web services. Service providers, rather than defining different services for different client use cases, now define a single more abstract service, which clients adjust to their individual needs.
  • UML as a possible way to describe the service: UML notation (used in this document) is a possible way to express the information model. Although UML is not a requirement for modeling services and data objects (users can directly code their own WSDL and XSD according to WS response template specifications), there is significant tooling available to convert UML into proper WSDL, XSD, and WS response template implementations exit to automatically create the more flexible WS response template-aware WSDL.
  • Easier maintenance and compatibility: Service providers can extend their existing WS response template services without impact to existing clients. By extension, we mean adding a new property in a data structure: in that case, the existing clients do not require this property in the request so they will not get it in the response from the new implementation; only clients who require this new property (especially new clients) will get it in the result.
  • Extra Overhead: The WS response template solutions does have some extra overhead. Requests transmit more data than a typical Web services solution, because additional information is required to prune and filter the resulting object graphs, since each item desired in the response must be specified in the request. In addition, extra code is executed on the server to process a WS response Template request. This overhead is not excessive, but WS response template is obviously not as effective in all cases.

Related patterns

The following are related patterns are related to the WS response template pattern:

  • The requester sde caching pattern (RSPC):The WS response template is ideally targeted at multi clients where the data requrement of those client is not known at service specification time. Similar usage scanarios exist where once the initial invocation is make the requester makes the same request repeatly. This WS response template pattern does not support this since this would involved maintain state between the requester and the provider however it can be combined with the requester side caching pattern (See Resouces) to sadify performance quality of service constraits.

Conclusion

We have examined the WS response template pattern specification in detail here. This pattern soecification follows the outline of patterns as specficied in the book titled "Design patterns" by Gamma et al. In a future article we will return to this pattern specification and provide an implementation of this pattern specification using the model driven development environment of IBM flag ship development product, Rational Software Architect

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=103816
ArticleTitle=Web services response template pattern: a specification
publish-date=02102006