CA API Gateway 9.1

9.4 9.1

Configure Namespaces

This topic describes how to work with namespaces in the gateway.
gateway83
This topic describes how to work with namespaces in the
CA API Gateway
.
Namespace Map
The Policy Manager cannot predict which namespace prefixes, if any, might be found in the messages that will be received by the
API Gateway
. To allow the use of namespace prefixes in XPath expressions, the
API Gateway
supports a user-editable namespace map attached to any XPath-based assertion (the Evaluate Request XPath, Evaluate Response XPath, and Require XPath Credentials assertions). Without namespace prefixes, constructing correct and namespace-aware XPath expressions is extremely complicated. For example, a correct, namespace-aware XPath expression that will match the top-level Envelope element in a SOAP 1.1 message without using prefixes is:
/*[local-name()="Envelope" and namespace-uri()="http://schemas.xmlsoap.org/soap/envelope"]
Since the http://schemas.xmlsoap.org/soap/envelope namespace URI is typically declared in the namespace map under the prefix "soapenv", the same XPath expression can be rewritten just as correctly as:
/soapenv:Envelope
To allow a given prefix to be used in the XPath expression in an XPath-based assertion, an entry for the prefix must be present in the assertion's namespace map. Using the custom mapping feature, a namespace map can be defined and saved in the Evaluate Request XPath assertion. For XML applications, custom namespace mapping is essential for defining the XPath query pattern for incoming XML request messages. For SOAP web services, the namespace list is automatically populated with the namespaces declared in the WSDL. New namespaces can be added and removed from the default namespace list, but the default namespaces themselves cannot be removed or changed.
Namespace prefixes that may appear in messages received by the
API Gateway
 are unrelated to those found in the namespace map of XPath-based assertions, even if they may happen to be identical. In order for an XPath expression using prefixes to match namespace-qualified nodes in a message, the message's namespace URIs must exactly match those found in the assertion's namespace map. For example, consider the following simplified SOAP 1.1 message:
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope">
  <Body>
    <someApplication:operationName xmlns:someApplication="urn:example.com:someApp"/>
  </Body>
</Envelope>
Even though this message's Body element appears without a namespace prefix, it is still qualified with the standard SOAP 1.1 namespace URI. The naive XPath expression "//Body" might match this particular message, but would fail to match another message that happened to employ a prefix for the SOAP 1.1 namespace URI. With the namespace map feature, the expression "//soapenv:Body" can match any message that uses the correct namespace URI, regardless of what prefix, if any, it uses to declare it.
Editing the Namespace Map
You cannot change or remove the namespaces originating from the WSDL document, but you can modify the namespace map in the following assertions:
Encrypt Element 
Evaluate Request XPath 
Evaluate Response XPath 
Sign Element 
Require XPath Credentials 
To modify the namespace map
:
  1. Open the properties for any of the assertions listed above.
  2. Click [
    Edit Namespaces
    ]. The Edit Namespaces and Prefixes dialog appears with the default WSDL namespaces and prefixes.
  3. Choose an action to perform:
    To...
    Do this...
    Add a new namespace prefix
    1. Click [
      Add
      ].
    2. Enter the
      Prefix
       and
      Namespace URI
       for the new namespace.
    3. Click [
      OK
      ]
    Edit a user-defined namespace prefix
    Select a user-defined namespace prefix to edit. These are shown in bold.
    1. Click [
      Edit
      ].
    2. Modify the
      Prefix or Namespace URI
      .
    3. Click [
      OK
      ].
    Only user-defined namespaces may be edited (those entered using the [
    Add
    ] button). Predefined namespaces cannot be modified.
    Delete a user-defined namespace prefix
    1. Select the user-defined namespace prefix. These are shown in bold.
    2. Click [
      Remove
      ]. The entry is removed immediately.
    Only user-defined namespaces may be removed (those entered using the [
    Add
    ] button). Predefined namespaces cannot be removed.
  4. Click [
    OK
    ] to close the dialog.
Migrating Namespaces
The Migrate Namespaces feature allows you to quickly update all XPath-based assertions from one namespace to another. The XPath-based assertions include the following:
"Encode to MTOM Format Assertion"
"Encrypt Element Assertion"
"Evaluate Request XPath Assertion"
"Evaluate Response XPath Assertion"
"Require Encrypted Element Assertion"
"Require Signed Element Assertion"
"Require XPath Credentials Assertion"
"Sign Element Assertion"
To migrate namespaces
:
  1. In the policy window, select the assertion(s) to migrate. You can select multiple assertions by holding down the [
    Ctrl
    ] key while selecting the assertions. To update all eligible assertions in the policy, select the first assertion in the policy, hold down the [
    Shift
    ] key, then select the last assertion in the policy. 
  2. In the Policy Manager, select [
    Edit]
     >
    Migrate Namespaces
     from the Main Menu (browser client: use the "Edit" menu next to the "Help" menu within the client). 
    If the option is not available, click on an assertion in the policy window first.
    The Migrate Namespaces dialog appears.
  3. Enter the original namespace or select a namespace from the drop-down list.
  4. Enter the new namespace or select from a list of common namespaces from the drop-down list.
  5. Click [
    OK
    ]. All XPath-based assertions listed above are automatically updated to use the new namespace.

Content feedback and comments