Translation filter

Purpose

The Translation filter translates requests and responses so that services receive requests in the format that they expect and clients receive responses in the format that they prefer. The translation files consumed by the Translation filter (for example,  some-translation-file.xsl ) may be placed at any valid location accessible by the Repose node.

General filter information

Filter name: translation

Filter configuration: translation.cfg.xml

Released: version 2.4.0

Prerequisites

Headers: The Translation filter has no required request headers.

Filter order: The Translation filter has no required preceding filters.

Standard filter order:  Place the Translation filter last in your filter chain.

Basic translation configuration

Configure the Translation filter by editing the translation.cfg.xml file.

1. Set Up Repose 
Configure Repose using either a cluster or a single instance configuration.

2. Add the Client Authentication Filter 
Add the Translation filter to your system model configuration. Place this filter last in your filter chain.

3. Configure the Translation Filter 

Configure the request and response translation using the following structure:

Optional configuration examples

Example 1: Remove an element

The following translation.cfg.xml will apply two style sheets (identity.xsl and remove-element.xsl) to responses with status code 2xx and content type of application/xml if the Accept is also application/xml. The output of the translation chain will be application/xml. Two parameters (my-param and my-param2) will be passed to the identity.xsl.

Configuration 1 - response

Testing application/xml - response

Output

In the resulting output, the remove-me element and its contents will be removed:

<a>Stuff</a>


Example 2: Add an element

The following translation.cfg.xml will apply two style sheets (identity.xsl and add-element.xsl) to responses with status code 2xx and content type of application/xhtml+xml if the Accept is application/xml. The output of the translation chain will be application/xml. 

Configuration 2 - response

Testing application/xhtml+xml - response

Testing application/xhtml+xml - request


Output

In the resulting output, the add-element style sheet will add a new container element called add-me.

<add-me><a>Stuff</a></add-me>


Example 3: Convert JSON to JSONx

JSON content is converted into JSONx prior to sending the content to the style sheet chain.  For example, if the following JSON is sent in the request: 

Click here to read more about JSONx.

Configuration 3 - response

Testing application/xml - response


Output

Example 4: Convert JSON --> JSONx --> JSON

This example will convert JSON to JSONx, apply the identity translation, and then convert JSONx back to JSON. In order for your origin service to receive JSON, you must add line seven to your configuration. Otherwise, the request or response body will remain in JSONx.

Configuration 4 - response



Testing application/xml - response


Testing application - request

Output
 { "field1":"value1", "field2":"value2" }


Example 5: Convert XML to JSON

Configuration 5 - response

Testing application/json - response

Place the attached Translation filter file in the directory the curl command is being run from, to be able to get translated JSON output as shown.

Output

Example 6: Convert XML to Atom

This example will convert XML to an Atom feed.

Configuration 6 - response

Testing application/atom+xml - response

Place the attached version.xml file in the directory the curl command is being run from, to be able to get translated Atom feed output as shown.

Output

Example 7: Convert XML to HTML

This example will convert XML to HTML.

Configuration 7 - response

Testing application/xml - response

Place the attached version.xml file in the directory the curl command is being run from, to be able to get translated html output attached.



Output

Example 8: Embedded XSL

By using an xsl element within the style element, xsl can be directly embedded into the translation configuration file.

Example 9: Header transformation

This example will demonstrate how to transform a given header to a desired header.

Example 10: URI and Query Transformation

This example will demonstrate how to transform path segments in the URI into query parameters for all requests.

Configurable parameters

XML schema definition

Example configuration

The translation.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the System Model Configuration.

ElementsAttributes

Required/

Optional

Description
<translation>-RequiredSpecifies the sub-elements and attributes to define your translation configuration.

<allow-doc-type>

-OptionalIf false, then any request/response body that contains an DOCTYPE section will be rejected.  If true, then DOCTYPE sections will be allowed.  However, repose will limit the entity definitions allowed in these sections.  Default is false.

<multi-match>

-OptionalIf true, then all translation chains that match the request will be applied in the order in which they are defined in the configuration.  If false, then only the first translation chain to match the request will be applied.  Default is false.  This attribute was added in version 2.6.8.

<xsl-engine>

-Optional

Select the XSL parser from the list.  

  • SaxonHE
  • SaxonEE

SaxonHE is the default. SaxonEE has initial support for XSLT 3.0 and requires a Saxon license.  This attribute was added in version 2.7.1.

<response-translation>

<request-translation>

-OptionalThe enumerated translation specifies a chain of stylesheets to be applied to a request response body and the criteria for when the chain should be applied.  All of the criteria must match before a chain is applied.  Both the <response-translation> and <request-translation> nodes have the same attributes & abilities.
http-methodsOptionalList of HTTP methods associated with this rate limit.
code-regexOptionalCode regex specifies for which response codes this style sheet chain should be applied. This is a regex.  
For example, 4[\d]{2} would match all response codes in the range from 400 to 499.
content-typeOptionalContent type specifies for which response content types this style sheet chain should be applied.  
For example, application/xml.
acceptOptionalSpecifies to which Accept type this chain should be applied.
For example, application/xml.
translated-content-typeOptionalSpecifies the content-type which is output by this chain. The response content-type is set to this if the style sheets are applied successfully.
<style-sheets>-RequiredContains the list of style sheets to be applied for this translation chain.
<style>-OptionalSpecifies one style sheet within the chain.  
idRequired only if using style.Unique id for this style sheet.
hrefNot required if style is embedded.URI which specifies the location of the style sheet. If a relative path is specified, then this will be relative to the REPOSE configuration directory.
<param>-OptionalSpecifies the attributes that define the parameters to be passed in to the transformer for the style sheet.

nameRequired only if using param.Name of the parameter to be passed in to the transformer for the style sheet.

valueRequired only if using param.Value of the parameter to be passed in to the transformer for the style sheet.
<xsl>-OptionalA style sheet can contain an embedded XSL. The embedded XSL would be placed within an xsl element within the style element.  If the XSL is embedded, then the href attribute of the style element would not be specified.

Return codes and conditions

This filter does not return specific response codes. The request will simply pass through to the next filter or to the origin service.

Translation filter notes

SAXON 9.4 functionality

The translation component processes requests and responses with XSLT 2.0 stylesheets.  If a SaxonEE license is installed, the XSLT 3.0 functionality can be enabled.  See the documentation on the xsl-engine attribute of the translation node for more information.

User defined entities in requests

As of Repose 2.6.0, the translation component will automatically remove, without expanding, user defined entities from requests and responses.  This is to prevent XXE attacks against Repose or any service behind Repose.

JSONX Translation for the message content

The translation component allows services to receive request message content as JSONx when the message content of the request that is sent to the service is JSON. JSON content will automatically be converted to JSONx when the request or response body contains JSON data.  See below for an example.  Click here to read more about JSONx.

JSONx content can be converted back to JSON by using the jsonx2json.xsl style sheet (attached; see below).

Dynamic translation XSLT updates

The translation component allows dynamic updates so that the translation XSLT files can be updated at runtime.

Sample files

The preceding examples use these XSL files and Repose configuration files. Using these files, after updating container.cfg.xml to use appropriate paths, you can run the example cURL commands. Click the arrow on the right of each sample to expand the source.