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
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.
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.
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.
The uri-normalization.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the System Model Configuration.
|<uri-normalization>||-||Required||Specifies the sub-elements and attributes to define your URI normalization configuration.|
|<media-variants>||-||Optional||Lists the media types to apply to specific media variants from the request URI.|
|<media-type>||-||Optional||Defines the media type that is normalized.|
|name||Required only if using media-type.||Names the media type to apply to the accept header of the request.|
|variant-extension||Optional||Defines the variant extension that the configured media type applies to.|
|preferred||Optional||Defines the default media type to apply to the request if no media type variation or accept type is supplied. |
|<uri-filters>||-||Optional||Lists 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-regex||Optional||Defines a regular expression that is matched against incoming requests.|
|http-methods||Optional||Lists the method or methods that this target matches against. Valid values are GET, DELETE, POST, PUT, HEAD, OPTIONS, CONNECT, TRACE, and ALL.|
|alphabetize||Optional||Rearranges the query parameters in alphabetical order.|
|<whitelist>||-||Optional||Lists the set of parameters that are allowed to pass to the origin service.|
|id||Required only is using whitelist.||Uniquely identifies the whitelist.|
|<parameter>||-||Required only if using whitelist.||Lists the multiplicity and the case-sensitive parameters.|
|name||Required only if using whitelist.||Indicates the value of the query parameter.|
|multiplicity||Optional||Indicates 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-sensitive||Optional||Controls 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.
You can configure the URI Normalization filter to create accept headers.
- 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