SOAP Optimisation Modules: Response Caching

Mark Nottingham,
2001 Akamai Technologies

  1. Module Description

    1. Status of this Document
    2. Notational Conventions
  2. Cache Model
  3. Input Specification

    1. Namespace
    2. ResponseCache Header Block
    3. Example
  4. Processing Rules
    1. Response Processing
    2. Request Processing
    3. Coherence Directives
  5. Output Specification
  6. Exceptions
  7. Security Considerations
  8. References
  9. Appendix A: Using the Response Caching Module with the SOAP RPC Convention

1 Module Description

Web Service deployments often require more scalability, availability and performance than a single server can provide. This specification defines a means of caching SOAP [SOAP] response messages by clients and intermediaries, through use of a SOAP Module.

The Response Caching module enables caching of entire response messages in request/response message exchange patterns, including attachments if present, over any SOAP transport binding. Its cache is indexed based upon aspects of request messages which are selected by blocks inserted into response messages. This Module does not enable granular caching of the response; such a facility can be provided either by extensions to it, or by separate Modules.

1.1 Status of this Document

This document is a draft circulated for comment only; it has not been implemented. Discussion should be directed to the author and/or the mailing list.

1.2 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 [KEYWORDS].

2 Cache Model

Response Caching is directed by a response Header block; unlike HTTP caching (where the client can send Cache-Control directives), the server has exclusive control over cache coherence. Additionally, coherence is explicit; whilst the HTTP allows a heuristic to be used to determine freshness, Response Cache implementations MUST NOT cache responses which do not contain explicit coherence information. Although this version of the specification only includes one cache coherence mechanism (and no means of validation or invalidation), it is anticipated that these mechanisms will be defined by future revisions and/or extensions.

Response caching is implemented by three distinct caches; the Message Cache, the Service Expression Cache and the Message Expression Cache.

The Message Cache contains individual SOAP messages which have been cached, and is indexed by both the Service Key (which identifies the particular Web Service being accessed) and the Message Key (which contains to the combination of request charateristics that determine whether the cached response can be used). This dual-key approach accommodates the common practice of exposing multiple Web Services through a single Service URI.

The Service Expression Cache contains the XPath expression which is used to determine the Service Key for a particular Service URI, and is indexed by the Service URI.

The Message Expression Cache contains the XPath expressions which are used to determine the Message Key for a particular Service Key, and is indexed by the Service Key.

This design allows for one Service Expression for each particular Service URI, and one Message Expression for each Service Key. If the cache encounters a Service or Message Expression which is different from that in the appropriate Expression Cache, all Message Cache entries which are indexed by that Expression MUST be evicted from the cache.

3 Input Specification

3.1 Namespace

The XML namespace [XML-NS] URI that MUST be used by implementations of this specification is:

The namespace prefix "SOAP-OPT" used in this specification is associated with this URI.

3.2 ResponseCache Header Block

This module defines one block, 'ResponseCache', that may be inserted into response message Envelopes. Its schema [XMLSchema] is:

  <import namespace="" />

  <element name='ResponseCache'>
        <element name='SOAP-OPT:serviceKey' 
         type='xsd:string' minOccurs='0' />
        <element name='SOAP-OPT:messageKey' 
         type='xsd:string' minOccurs='1' 
         maxOccurs='unbounded' />
        <element name='SOAP-OPT:coherence'>
            <element name='SOAP-OPT:delta-freshness' 
             type='xsd:positiveInteger' />
      <attribute ref='SOAP-ENV:actor' use='optional' />
      <attribute ref='SOAP-ENV:mustUnderstand' use='optional' />
      <attribute name='id' type='ID' use='optional' />

The following additional constraints are placed upon particular values;

3.3 Example


Here, the Service Key is the namespace and local name of the first child of the Body (as would be used for RPC messages), and the message key is the content of the 'symbol' element, along with the content of the 'exchange' attribute on the 'symbol' element. Messages cached as a result will be considered fresh for 300 seconds.

4 Processing Rules

4.1 Response Processing

Upon receiving a response message which contains a Response Caching block, implementations MUST:

  1. If the Service Expression Cache doesn't contain an entry for the Service URI, populate its value with the XPath expression contained in the 'serviceKey' element information item.
  2. Otherwise, compare the value of the cached Service Expression with that presented in the response message's 'serviceKey' element information item. If they differ, replace the Service Expression, and evict all cached Messages for that Service URI.
  3. Calculate a Service Key, by concatenating:
    1. The Service URI
    2. If the 'serviceKey' element information item is present, the result of evaluating XPath expression contained within, with the SOAP message's 'Envelope' element as the context node.
  4. If the Message Expression Cache doesn't contain an entry for the Service Key, populate its value of the XPath expression(s) contained in the 'messageKey' element information item(s) (concatenating them into a list, if appropriate).
  5. Calculate a Message Key, by concatenating:
    1. For each 'messageKey' element information item, the result of evaluating the XPath expression contained within, with the SOAP message's 'Envelope' element as the context node.
  6. Store the entire response message in the Message Cache (including attachments, as appropriate), indexed by the Service Key and the Message Key. Any existing cache entry which matches MUST be replaced.
  7. Continue response message handling as normal.

If a cached response is used, the SOAP node which implements the cache MUST process any remaining blocks in the message before returning the response, as determined by the SOAP processing model (i.e., blocks before the caching block in the message's processing order will be processed prior to caching; those afterwards will be processed subseqently, each time the cached message is used).

4.2 Request Processing

Upon receiving any request message, implementations MUST:

  1. Determine if a cached response message exists by recalculating and searching for the Service Key, then the Message Key.
  2. Determine if the cached message is fresh, based on the the 'coherence' element information item (see below)
  3. If the cached message is fresh, it SHOULD be used as the response message without forwarding the request message.
  4. Otherwise, the cached response message SHOULD be evicted from the cache, and request message processing should continue as normal.

4.3 Coherence Directives

The children of the 'coherence' element information item are used to control cache coherence. Currently, only one possible child is defined;

5 Output Specification

By default, implementations SHOULD regenerate the ResponseCache block in responses, to allow operation of downstream caches.

6 Exceptions

No Faults are specified; if a failure occurs, implementations SHOULD operate as if the cache were not present; i.e., forward the request message.

To ensure correct operation, implementations which generate ResponseCache blocks SHOULD check included XPath expressions for correctness.

7 Security Considerations

This specification defines a mechanism that allows SOAP intermediaries and SOAP clients to response authoritiatively to requests, by using cached responses. Although this does not introduce any new vulnerabilities to SOAP, applications which use it should understand the security implications of explicitly allowing caching, especially if authentication, authorization or encryption is applied through another Module.

8 References


W3C Note, "SOAP: Simple Object Access Protocol 1.1," 08 May 2000.

S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels," RFC 2119, Harvard University, March 1997
W3C Recommendation, "Namespaces in XML," 14 January 1999.
W3C Recommendation, "XML Schema Part 0: Primer," 2 May 2001.
W3C Recommendation, "XML Path Language (XPath) Version 1.0," 16 November 1999.

Appendix A: Using the Response Caching Module with the SOAP RPC Convention

Currently, most SOAP applications use the RPC convention. To enable Response Caching for these applications, the following Service Key is suggested:



This assigns the service key to the first child of the SOAP Envelope's 'Body' element, including both its namespace-uri and local-name. When the RPC convention is in use, this element is the root of the serialization graph of the request (i.e., the method of the RPC request).

revision: 2001/08/23