XML API Gateway

with XML Schema, XPath, and XSLT Support

XML is still present in enterprise systems and APIs. In some domains, it remains the dominant data format and will continue to do so. At the same time, modern APIs are typically based on JSON. As a result, XML and JSON-based systems must work together.

An API Gateway with strong XML support allows you to fully support legacy APIs and helps bridge the gap between XML services and modern API architectures.

This page explores different kinds of XML support and integration in API Gateways. The examples are based on the open source Membrane API Gateway. Other gateways offer similar XML capabilities, but their level of support and configuration options can vary.

1 XML-Based Routing

In most APIs, routing is based on the request path. With XML messaging, the document itself becomes the main source of routing information. Instead of looking at the URL, routing decisions are usually made based on XML elements in the message body.

XPath allows you to express routing rules that match XML messages. In the example below, requests are routed to the API only when the XML payload contains a getCity element in the right namespace.

api:
  port: 2000
  test: //c:getCity
  language: xpath
  xmlConfig:
    namespaces:
      - prefix: c
        uri: https://predic8.de/cities/

2 Accessing XML Content with XPath

XPath is a query language for extracting values from XML documents. In Membrane, it is available as an expression language and can be used across many plugins and interceptors. The following examples show typical use cases.

Setting an HTTP header based on a value from the XML body:

- setHeader:
    name: X-OrderId
    value: ${/order/@id}
    language: xpath

Logging only the number of items instead of the full payload to keep the log output small:

- log:
    message: Number: ${count(//order/items/item)}
    language: xpath

A conditional that makes gateway behavior dependent on XML content:

- if:
    test: //order[@priority='high']
    language: xpath
    flow:
      - log:
          message: High priority order detected

Other common uses of XPath include setting properties, extracting session data, or computing values for rate limiting and quotas.

The sibling of XPath is JSONPath. All examples above can also be implemented with JSONPath. It follows a similar idea but operates on JSON instead of XML.

Sidenote: What is XPath?

XPath is a query language for selecting and extracting values from XML documents. XPath expressions can also be evaluated as boolean conditions, for example to control routing, logging, or transformations.

3 XML Schema Validation

XML Schema precisely defines the structure of an XML document. Requests and responses can be validated against a schema and rejected if they do not match. This improves security and helps stop invalid data early at the API Gateway. Which is useful in data and legacy integration.

In Membrane, WSDL validation extends XML Schema validation to SOAP messages. Because a WSDL describes all request and response message types, it provides a convenient way to configure validation for web services.

4 XML Message Transformation

An API Gateway can transform XML messages into other formats, such as JSON or plain text. It can also convert between different XML structures. The reverse direction, for example from JSON to XML, is equally possible.

XML Message Transformation at the API Gateway

This is commonly used to bridge differences between systems. For example, an internal XML format can be transformed into a standardized XML format required by a business partner.

4.1 Templates with XPath

In Membrane, templates can be filled using JSONPath, Groovy, SpEL, or XPath expressions. The following example shows how XML documents can be transformed into JSON messages using a template together with XPath.

- setBody:
    language: xpath
    contentType: application/json
    value: |
      { "customer": {
            "id": ${/customer/@id},
            "name": ${/customer/name},
            "city": ${/customer/address/city}
        }
      }

4.2 XSLT

XSLT (eXtensible Stylesheet Language Transformations) is a rule-based language for transforming XML documents. It can convert XML into other text formats such as CSV, EDIFact, HTML, or different XML structures.

XSLT is powerful but has some drawbacks. It can be difficult to learn, and certain tasks such as complex computations or date handling are less straightforward compared to general-purpose programming languages.

One major advantage of XSLT is that it is a widely adopted standard. It has been used extensively in legacy integration projects. This makes it possible to migrate existing solutions, for example from an enterprise service bus (ESB) to an API Gateway, by reusing existing stylesheets. Reuse can significantly reduce migration effort and cost.

XSLT Message Transformation in an API Gateway

4.3 XML Transformation with Scripts

Scripting languages are a powerful tool for message transformation. Even short scripts can modify XML messages or transform them completely.

In Membrane, the groovy, template, setBody, and soapBody plugins support Groovy in addition to XPath and JSONPath. Groovy runs on the Java platform and provides strong XML support, including convenient parsers and builders for processing XML messages.

The following example uses Groovy and XmlSlurper to read values from an XML document and build a new XML response:

- groovy:
      def order = new XmlSlurper().parseText(body)
      def writer = new StringWriter()
      def xml = new groovy.xml.MarkupBuilder(writer)

      xml.priorityOrder {
        id(order.@id.text())
        customer(order.customer.name.text())
        priority(order.@priority.text())
      }

      return writer.toString()

4.4 XML to JSON and JSON to XML Transformation

JSON and XML share structural similarities that allow generic transformations between the two formats. In many cases, such conversions work well and save significant effort. However, there are important differences that cannot always be resolved automatically by a generic converter.

A common approach is to combine a generic conversion with a custom transformation step. The generic converter performs the main mapping, while a custom transformer handles adjustments such as renaming fields or converting unordered JSON properties into an ordered sequence required by XML.

5 Integration of Legacy XML Web Services

The features presented above are valuable when working with legacy XML-based web services or integrating them with modern APIs. Membrane provides several plugins with additional capabilities specifically designed for XML technologies such as SOAP and WSDL.

Resources

API Gateway Handbook

Further details on the concepts discussed above can be found in the following chapters of the API Gateway book, which can be downloaded for free.

Membrane XML Components

Generic xml2Json and json2xml converters
XSLT Transformer
XML Schema Validator
template with XPath support