The Content Normalization filter normalizes the headers and media type of the request by performing three separate functions. The filter uses blacklisting to prevent specific requests from passing to the origin service, it uses whitelisting to pass only approved headers to the origin service, or it uses media typing to normalize accept headers. The Content Normalization filter does not modify the response.
Required headers: The Content Normalization filter has no required request headers.
Required preceding filters: The Content Normalization filter has no required preceding filters.
Standard filter order: When you set the order of Repose filters, place the Content 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.
Basic content normalization configuration
Configure the Content Normalization filter by editing the content-normalization.cfg.xml file.
1. Set Up Repose
Configure Repose using either a cluster or a single instance configuration.
2. Add the Content Normalization Filter
Add the Content Normalization filter to your system model configuration. Place this filter near the top of the filter sequence below the SLF4j Logging filter.
3. Configure the Content Normalization Filter
- If you are using the Content Normalization filter to blacklist or whitelist configure <header-filters> with the appropriate sub-elements.
If you are using the Content Normalization filter to normalize media, configure the <media-type> element.
You may configure the Content Normalization filter to blacklist or whitelist headers and to normalize media using both the <header-filters> and the <media-type> elements in the configuration.
4. Test Content Normalization
- Send a request to a reflection service, such as http://httpbin.org, with the blacklisted header included.
- Check the response body for that header. If it is not there, the filter is configured properly
- Send a request to a reflection service, such as http://httpbin.org, with the whitelisted header included.
- Check the response body for that header. If it is there, the filter is configured properly.
- Send a request without a whitelisted header. If it is not there, the filter is configured properly.
Media type feature:
- Send a request to a reflection service, such as http://httpbin.org, that ends in the media-type that you want captured.
- Check the response for the appropriate Accept header. If it is there, the filter is configured properly.
The Content Normalization filter has three features that perform separate functions. The features are blacklist, whitelist, and media type.
Use the media-type feature to normalize the accept header by mapping a media type to a URI extension. The Content Normalization filter will strip the extension from the URI and set the configured media type name. The filter sets the accept header but does not change the content body of the request.
- If an accept header matches a configured variant extension, the configured media type is used.
If no accept header is present or if no accept headers match any media type in the list, the preferred media type is used.
|Headers Passed to Origin Service|
Use the blacklist feature to extract the headers that you do not want to pass to the origin service. The following example uses the blacklist element and the id attribute to name the HTTP headers that will be extracted from the request.
curl http://188.8.131.52:8887/v1/usertest1.xml -H "x-auth-token:358484212:99493" -H "black-listed1:should" -H "black-listed2:disappear" -H "nonblacklisted:should"
|Headers Passed to Origin Service|
Use the whitelist feature to list only the HTTP headers that you want to pass to the origin service. All other requests are extracted and are not passed on. The following example uses the whitelist element and the id attribute to name the only HTTP headers that will be passed to the origin service.
curl http://184.108.40.206:8887/v1/usertest1.xml -H "x-auth-token:358484212:99493" -H "X-Auth-Group:should" -H "X-Auth-Header:disappear" -H "X-Whitelisted-Header:allowed"
|Headers passed to origin service|
|<content-normalization>||-||Required||Uses the accompanying sub-elements and attributes to define your content normalization configuration.|
|-||Optional||Uses the blacklist or whitelist sub element to define the headers that are extracted or passed to the origin service.|
|-||Optional||Defines the list of headers that are extracted from the request.|
|-||Optional||Defines the list of request headers that are allowed to pass to the origin service.|
|-||Required only if using blacklist or whitelist.||The header that will be blacklisted or whitelisted.|
|id||Required only if using header.||Unique identifier of the given group.|
|-||Optional||Defines a list of accept headers for the URIs that match a configured variant-extension.|
|-||Optional||Defines the media type that will be normalized.|
|name||Required only if using media-type.||Names the media-type.|
|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.|
Return codes and conditions
- The Content Normalization filter never returns error codes. The request will simply pass through to the next filter or the origin service.
- The Content Normalization filter extracts content that is configured, ignores everything else, and lets the request pass to the origin service.
Content normalization use cases
- As an administrator, I want to prevent a malicious user from programmatically altering request parameters or headers that prevent caching of responses. My service caches responses based on request URIs, parameters, and headers so that it can respond quickly with little load on the service.
- As an administrator, I want my service to support requests with multiple media types in the URL extensions.
Request headers created
You can configure the Content Normalization filter to create accept headers.
Content normalization process
- The client sends the request.
Repose processes the request with the blacklist or whitelist feature, or with the media type feature.
The media-type feature may be used with the blacklist or the whitelist feature. However, the blacklist and whitelist features should not be used simultaneously.
- Repose sends the request to the origin service.
- The origin service processes the request.
- The origin service returns the response.
- Repose passes the response. (The Content Normalization filter does not modify the response.)
- Repose returns the response to the client