URI Normalization filter

Purpose

Normalization is the process of modifying or standardizing content to optimize the flow of information. The URI Normalization filter normalizes requests by performing two separate functions. The filter uses the whitelist element to prevent cache busting and uses the media-type element to normalize accept headers.

General filter information

Filter name: uri-normalization

Filter configuration: uri-normalization.cfg.xml

Released: version 2.1.0

Prerequisites

Required headers: The URI Normalization filter has no required request headers.

Required preceding filters: The URI Normalization filter has no required preceding filters.

Standard filter order: When you set the order of Repose filters, place the URI Normalization filter near the top of the sequence to clean the request. This sequence prevents unexpected request headers and content from passing to the origin service.

URI normalization configurations

The URI Normalization filter has two features that perform separate functions. The features are whitelist and media type. 

 

Configuration examples

Request

curl http://origin.service/action?a=3&b=4&a=4&A=0
Parameters allowed

a=3

a=4

A=0

 

 

Whitelist

Ensure that data is cached by using <whitelist> to control the query parameters and multiplicity to control the number of times a query parameter appears. This normalizes the requests coming from the client so that cache busting cannot occur.

 

 


Media type

Use the media-type feature to normalize the accept header by mapping a media-type to a URI extension. If the media-type extension of the URI matches a configured variant extension, the URI Normalization filter strips the extension out of the URI and sets the configured media-type name. The filter sets the accept header but does not change the content body of the request.

Request
curl http://origin.service/action?l=1&m=2&N=3&p=4&n=5&n=6
Parameters allowed

l=1

m=2

N=3

p=4

n=5

n=6

Configurable parameters

XML schema definition

Example Configuration

The uri-normalization.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
<uri-normalization>-RequiredSpecifies the sub-elements and attributes to define your URI normalization configuration.
<media-variants>-OptionalLists the media types to apply to specific media variants from the request URI.
<media-type>-OptionalDefines the media type that is normalized.
nameRequired only if using media-type.Names the media type to apply to the accept header of the request.
variant-extensionOptionalDefines the variant extension that the configured media type applies to.
preferredOptionalDefines the default media type to apply to the request if no media type variation or accept type is supplied. 
<uri-filters>-OptionalLists the targets for which to apply normalization to the query parameters.
<target>-Required only if using uri-filters.Specifies the endpoint and http-method for a given uri-regex or http-method to act against. 
uri-regexOptionalDefines a regular expression that is matched against incoming requests.
http-methodsOptionalLists the method or methods that this target matches against. Valid values are GET, DELETE, POST, PUT, HEAD, OPTIONS, CONNECT, TRACE, and ALL.
alphabetizeOptionalRearranges the query parameters in alphabetical order.
<whitelist>-OptionalLists the set of parameters that are allowed to pass to the origin service.
idRequired only is using whitelist.Uniquely identifies the whitelist.
<parameter>-Required only if using whitelist.Lists the multiplicity and the case-sensitive parameters.
nameRequired only if using whitelist.Indicates the value of the query parameter.
multiplicityOptionalIndicates the number of times the parameter can be repeated in the query string. If you do not set the number of allowed occurrences, multiplicity is set to the default 0. If more than the number of allowed occurrences is provided, all occurrences after the maximum are stripped.  If the alphabetize attribute is set to true, the query parameters are first alphabetized and then evaluated for multiplicity. Multiplicity is unlimited in a given parameter.
case-sensitiveOptionalControls whether or not to remove parameters of a different case.

Return codes and conditions

  • The URI Normalization filter never returns error codes. The request simply passes through to the next filter or to the origin service.
  • If you use an HTTP method other than GET, DELETE, POST, PUT, HEAD, OPTIONS, CONNECT, TRACE, or ALL, you get a configuration error.

Request headers created

You can configure the URI Normalization filter to create accept headers.

Use cases

  • As an administrator, I want to prevent cache busting to alleviate load on the API node for better performance.
  • As an administrator, I want my service to support requests with multiple media types in the URL extensions.

URI normalization process

A typical URI Normalization filter process is summarized in the following diagram:

Request/Response Lifecycle for the URI Normalization Filter