Web services response template pattern: a specification
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.
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?
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.
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:
After applying the pattern the operation signature would change as follows:
RequestTemplate and the
ResponseTemplate are based on the original value object with the following modifications:
RequestTemplateis loosely typed and all the attributes are optional. The
RequestTemplatecontains a description of what should be in the
ResponseTemplateis strongly typed and all the attributes are optional. The
ResponseTemplatecontain the information from the orginal
ValueObjectbut in a form dictated by the requester given in the
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
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
Figure 3 shows the sequence diagram for the WS response template pattern.
Figure 3. 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.
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.
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.
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.
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
- Download a free trial version of Rational RequisitePro Rational RequisitePro V2003.06.15.
- Download a free trial version of Rational Software Architect Rational Software Architect V6.0.
- Build your next development project with IBM trial software, available for download directly from developerWorks.
- IBM Alphawork provides a reference implementation of the RAS called Reusable Asset Specification Repository for Workgroups, this reference implementatiion is available for download directly from alphaWorks.
- Visit IBM's Pattern solutions and find out what IBM is doing around patterns and reusable assets.
- Learn more about implementation of the WS response template pattern on alphaWorks.
- Learn more about the modeling of software services in Rational Software Architect with the UML 2.0 Profile for Software Services.
- Vist the Enterprise integration solutions (EIS) web site to learn more about what IBM is doing around SOA. Enterprise Integration Solutions (EIS) of IBM Software Group is part of IBM's corporate Software Strategy and Technology organization. The team controls and develops all of IBM's SOA related software products.