URI Stripper filter

Purpose

The URI Stripper filter allows Repose to strip out a specific section of the request URI, request body, edit the 'Location' header if there is one present in the response, and replace the stripped out section of the request URI in links contained in the body of the response.

General filter information

Filter name: uri-stripper

Filter configuration: uri-stripper.cfg.xml

Released: version 2.9.0

Prerequisites

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

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

Standard filter order:  When you set the order of Repose filters, place the URI Stripper filter at the bottom of the filter sequence. 

Basic URI stripper configuration

The URI Stripper filter can be configured by editing the uri-stripper.cfg.xml. The user can specify the following element:


token-index: When the URI Stripper filter receives a request it will parse the request path using the '/' character as the delimiter and break the path into indexed tokens. Starting from index '0' the URI Stripper will take the element in configured token-index and remove it from the request path. This same logic can also be applied to links in the request body if there is a request element in the configuration. The request element can also indicate different token-index if it the same one defined for the request path should not be used.


Resource pathToken indexValueStripped resource path
/v1/12345/some/resource112345/v1/some/resource
/path/to/some/resource/here3resource/path/to/some/here
/1
/


rewrite-location: If configured, the URI Stripper filter will try to put the removed token back into the resource path of the Location Header. To do this, the URI Stripper will attempt to preserve the tokens which preceded and succeeded the token that was stripped from the original URI. If the token which preceded the stripped value is present then the stripped value is added after the preceded value. If succeeded token is present instead then the stripped token will be inserted before the succeeded value. If neither, preceded or succeeded, values are present then the URI stripper will not attempt to insert the stripped value into the Location header.


Resource pathToken indexValueStripped resource pathOriginal location header pathUpdated location header path
/v1/12345/some/resource112345/v1/some/resource/v1/some/resource/v1/12345/some/resource
/v1/12345/some/resource112345/v1/some/resource/v1/new/resource/v1/12345/new/resource
/v1/12345/some/resource112345/v1/some/resource/v2/some/resource/v2/12345/some/resource
/v1/12345/some/resource112345/v1/some/resource/totally/new/resource/path/totally/new/resource/path


link-resource: If configured, the URI Stripper filter will try to put the removed token back into the resource path of the links in the response body. To do this, the URI Stripper will first check if the user configured a token-index indicating where to put the removed token. Otherwise, the filter will attempt to preserve the tokens which preceded and succeeded the token that was stripped from the original URI. If the token which preceded the stripped value is present then the stripped value is added after the preceded value. If succeeded token is present instead then the stripped token will be inserted before the succeeded value. If neither, preceded or succeeded, values are present then the URI stripper will behave based on the configured value of the link-mismatch-action attribute.


Configurable parameters

XML schema definition

Example configuration

The uri-stripper.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-stripper>-RequiredSpecifies the attributes to define your URI stripper configuration.
rewrite-locationRequiredThe rewrite location for the Location header.
token-indexRequiredThe token index to be removed from the request path.
<link-resource>-OptionalA specific ReST resource that contains one or more links which should have the stripped URI path segment re-inserted.

uri-path-regexOptionalA regex which will be matched against the URI path to determine if link modification should be attempted.

http-methodsOptional

List of HTTP methods for this resource on which links should be modified.

The legal values are:

  • GET
  • DELETE
  • POST
  • PUT
  • PATCH
  • OPTIONS (See Note 2)
  • TRACE
  • HEAD (See Note 2)
  • CONNECT (See Note 2)
  • ALL (Default)

NOTE 1: This attribute is not allowed to contain an empty value if present.

NOTE 2: Even though these values are legal, they have restrictions on them that make them inappropriate in this context and should NOT be used.

<request>-Optional
(Either request or response must exist) 
A container for paths which indicate that links should be modified on the request.
<response>-

Optional
(Either request or response must exist)

A container for paths which indicate that links should be modified on the response.
<json>-Optional

A JSONPath expression which identifies the location of a link 

token-indexOptionalThe URI Stripper filter will parse the links in the body of a request or response into tokens using the '/' character as a delimiter, strip from the request or re-insert the stripped token from the request URI into the response, then rebuild the link. Index '0' is the first path segment. If this attribute is not present, requests will use the token-index defined at the root level and responses will re-insert the stripped token after the token that preceded it in the request URI, or if that does not exist, before the token that succeeded it in the request URI.

link-mismatch-actionOptional

The action to take when a link cannot be found at a path, or when a link is found, but the configured path segment is out of bounds.

The legal values are:

  • continue – do not modify the response for the given link, and continue processing
  • remove – remove the field containing a link if it can be found, otherwise do not modify the response, then continue processing
  • fail (default) – stop processing and return a response with status code 500 and an empty response body


<xml>
OptionalSpecifies the XPath to the link to be modified
<namespace>
Optional
Specifies the Namespaces to the link to be modified

nameOptional (required if namespace is provided)The name that the namespace appears as under the XPath

urlOptional (required if namespace is provided)The url of the namespace that is used in the XPath
<xpath>
Optional (required if xml is provided)The XPath expression which identifies the location of a link

token-indexOptionalThe URI Stripper filter will parse the links in the body of a request or response into tokens using the '/' character as a delimiter, strip from the request or re-insert the stripped token from the request URI into the response, then rebuild the link. Index '0' is the first path segment. If this attribute is not present, requests will use the token-index defined at the root level and responses will re-insert the stripped token after the token that preceded it in the request URI, or if that does not exist, before the token that succeeded it in the request URI.

link-mismatch-actionOptional

The action to take when a link cannot be found at a path, or when a link is found, but the configured path segment is out of bounds.

The legal values are:

  • continue – do not modify the response for the given link, and continue processing
  • remove – remove the field containing a link if it can be found, otherwise do not modify the response, then continue processing
  • fail (default) – stop processing and return a response with status code 500 and an empty response body