Header Translation filter



The Header Translation filter can create new headers (in the request) using values from other headers.  You can optionally remove the original header and give the new header a new quality.

General filter information

Filter name: header-translation

Filter configuration: header-translation.cfg.xml

Release: version 2.8.3


Required headers: The Header Translation filter has no required request headers.

Required preceding filters: The Header Translation filter has no required preceding filters.

Standard filter order: If you are using other filters in your system model configuration, refer to the Standard Filter Order table to determine where to place the Header Translation filter.

Basic header translation configuration

Your header translation configuration in header-translation.cfg.xml will resemble the following example:

Header Translation Configuration
<?xml version="1.0" encoding="UTF-8"?>
<header-translation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://docs.openrepose.org/repose/header-translation/v1.0 ../config/header-translation.xsd" xmlns="http://docs.api.rackspacecloud.com/repose/header-translation/v1.0">
    <header original-name="Content-Type" new-name="rax-content-type"/>
    <header original-name="Content-Length" new-name="rax-content-length not-rax-content-length something-else" remove-original="true"/>
    <header original-name="X-Original" new-name="X-New" quality="0.7" splittable="true"/>

Configurable parameters

XML schema definition

Example configuration

The header-translation.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the system model configuration.




DescriptionVersion Availability
-RequiredSpecifies the sub-elements and attributes to define your header translation configuration.
<header>-RequiredSpecifies the list of headers that are translated.



Specifies the name of an existing header that you want to translate. The header is evaluated in a case-insensitive manner. Each header element must have a unique value for the original-name attribute.


RequiredSpecifies a space-delimited list of names that you want the original-name translated to.


OptionalRemoves the original headers. The default value is set to false.

If this attribute is set, the new header will be added using this quality.
If this attribute is not set, the new header will have the same quality as the original header (if any).
The default is to use the original header's quality.
splittableOptionalIf the original header contains multiple splittable values and a new quality is desirable (and configured), this attribute should be set to true to ensure all of the values get the configured quality. The default is false.
See the "Splittable Headers" section below for more details.

overwrite-targetOptionalIf set to true will overwrite any existing values currently under the new-name, instead of adding another value which is the default behavior.

Splittable Headers

When configuring a quality for the new headers, it is important to indicate whether or not the original header is splittable.  If the header is splittable but is not configured as such, not all of the header values will get the configured quality.  If you're not setting a new quality for the new header, it's not really important if the original header is splittable.


A non-splittable header will contain commas that do not signify separate values.  For example, the following value contains a comma but is meant to be a single value:

"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"


A splittable header can contain multiple values on a single line.  For example, the following header contains a total of 5 values:

"Accept": "text/html"
"Accept": "application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8" 

With a configured quality of 0.5, the following table displays the different outcomes of how the splittable attribute is set:




Return Codes and Conditions

  1. The Header Translation filter will never return an error code. The request will simply pass through to the next filter or the origin service.
  2. If the header to be translated is not included in the request, the header is ignored, and the request is passed through to the origin service. The filter does not expect the header to be present every time.

Request headers created

The Header Translation filter creates the headers that you configure in the header-translation.cfg.xml.

Use case

Your client’s coding change cannot be completed in time to deliver to the demands of your origin service. As an administrator, you want to change the name of certain request headers that come from the client so that the origin service will not reject the unrecognized requests.

Header translation process

  1. When a request enters the Header Translation filter, it will look for any header names that match the original-name attribute of the <header> element.
  2. If a request has a header that matches the value of an original-header attribute in the filter, then the filter adds headers to the request that correspond to the value or values in the new-name attribute.
  3. If the remove-original attribute is set to false, the request retains the original header so that the request is sent to the origin service with the original header and the new header or headers.
  4. If the remove-original attribute is set to true, the request is sent with just the new headers.

A typical Header Translation filter process is summarized in the following diagram:

Request/response lifecycle for the Header Translation filter