HTTP request transforms for configurable proxies

You're viewing Apigee X documentation.
View Apigee Edge documentation.

ConfigurablePREVIEW API proxy developers can quickly rewrite HTTP request paths, header, and query parameters using HTTP Request Transforms. Rewriting is enabled using a simple configuration that can reference incoming path template segments, header values, or query parameter values. This allows proxy developers to easily configure:

  • Path passthrough or replacement
  • Query parameter replacement
  • Header replacement

With HTTP request transforms support, configurable proxy developers can use the following techniques in request rewrites:

  • Mix constant character strings and variables
  • Reference wildcard segments from request paths as variables
  • Reference headers and query parameters as variables
  • Reference property sets as variables

Using HTTP request transforms in a configurable proxy

Configurable proxy developers can implement path, header, and query param rewrites directly in the config.yaml file using the http_request_transforms field available in the operations section of the proxy config.

For example, a proxy developer could implement rewrites to the path, query parameters, and request headers by defining the following API Operation HttpMatch in the config.yaml, as shown below: 

#config.yaml
base_path: /petstore/v1
…
operations:
- id: getDog
    http_match:
    - method: GET
      path_template: /dogs/{breed}/{name}
      
    http_request_transforms:
      path: /{headers.x-route-hint}/{path.breed}/{path.name}
      query:
        add:
          - name: dust
            value: {query.fleas}
            append: true
        remove:
          - fleas
      headers:
        add:
          - name: dog-breed
            value: {path.breed}
            append: false
        remove:
          - x-route-hint

For this example, assume the proxy is deployed, and the gateway receives the following HTTP request: 

GET /petstore/v1/dogs/keeshond/Shadow?fleas=true HTTP/1.1
X-Route-Hint: store123
…

The path is rewritten and delivered to the target backend service as the following: 

/store123/keeshond/Shadow?dust=true

Once parsed, the http_request_transforms section determines the URI rewrite. In this example, the path_template matches the original request on the /dogs/*/* pattern. This pattern extracts the path.breed and path.name variables as the values keeshond and Shadow, respectively. In addition, the query portion of the path is rewritten by adding a new query parameter (dust) with the value of query.fleas (true}, and removing the original query parameter (fleas). The path and query parameter rewrite processes are documented in greater detail below.

Available references for HTTP request transforms

HTTP request transforms in configurable proxies can utilize data references from Apigee property sets or variables in specified namespaces. The following table contains a list of available references for rewrites:

Reference type
Property sets Property set variables can be used for replacement. Their references are enclosed in double curly brackets: {{example}}.

Note: Property set references ({{ }}) are resolved prior to variable references ({ }). As a result, a property set reference may generate a variable reference.

Variables Variable references are enclosed in curly brackets: {example}.

All variable references must begin with a valid namespace (characters + .). See Available namespaces for variables.

Characters other than curly brackets are generally allowed in a variable reference identifier, if used after the namespace.

All reference variable values are calculated from the original request values. There are no reference values calculated based on other reference variables or rewritten values.

Referenced variables that are not defined or are unpopulated will return an empty string: ' '.

Available namespaces for variables

HTTP request transforms for configurable proxies supports the following namespaces for variables:

Namespace
{path.path_template_var}

Path template segment variables are referenced directly from the path namespace.

Once a path template name within the path_template field is declared as a labeled wildcard segment, that path template name can be used in the path rewrite field. For more information, see Using wildcards in path variables.
{header.header_name}

Header values can be referenced by name in the header namespace. Multiple header name values can be concatenated as a comma-delimited list of values.

Only valid header names can be used.

Pseudo headers (eg. headers starting with :, such as :scheme or :path) are not supported as variable references.
{query.query_parameter_name}

Query parameter values can be referenced by name in the query namespace. Multiple values for a query parameter can be concatenated as a comma-delimited list.

Only valid query parameter names can be used
{request.name} Request values can be referenced by name in the request namespace.
{request.path} The original path of the request, not including the query string, can be referenced.
{request.querystring} The original query string of the request (not including the ? separator) can be referenced.

Using wildcards in path variables

As referenced in the section above, wildcard (*) and double wildcard (**) path variables are supported in HTTP request transforms for configurable proxies. For a wildcard to be available as a template variable, it must be labeled with a name. Wildcards can be used anywhere in the path (but not in partial segments).

Guidelines for using single wildcards (*) :

  • A single wildcard matches a single segment.
  • A single named wildcard is declared as either {name} alone or {name=*}.

Guidelines for using double wildcards (**):

  • A double wildcard can match any number of segments.
  • A double named wildcard is declared as {name=**}.

    For example, the following declares {single-segment} and {multi-segment} as valid references: 

    path_template: /constant/{single-segment=*}/{multi-segment=**}
  • Any wildcard immediately following a double wildcard will be empty.

Path rewriting

The default behavior for processing the base_path in a configurable proxy is to remove the base_path prefix and pass the remaining path and query parameters to the target. However, it is possible to specify a path rewrite using the path field of the con.

The path field is a string that can consist of any combination of constant characters and path rewrite variable references. Variable references are declared inside curly brackets ({example}), as noted above.

Guidelines for using the path field in a configurable proxy to specify a path rewrite:

  • Constant characters can include any valid path character.
  • Dynamic replacement variables must conform to the Variable references specified above.
  • Any double slashes in the resulting path will be collapsed.
  • The path field can be used to rewrite any path segments, including the query string.

Header and query parameter rewriting

Headers and query parameters can also be rewritten using the query or headers fields in the configurable proxy config.

Guidelines for using the query or headers fields in a configurable proxy to specify a query parameter or header rewrite:

  • Values specified in the query.remove or headers.remove objects are always removed before values contained in the query.remove or headers.remove objects are added.
  • Values in the name fields are case insensitive.
  • The resulting values of add and remove pairs are delivered as separate elements, such as as multiple query parameters in the path or multiple headers, respectively.
  • Header and query names must comply with the corresponding RFCs (RFC7230 and RFC3986). Envoy pseudo headers that start with a colon (:authority ) are not permitted.

Overriding HTTP transformations

The entire http_request_transforms section can only be overridden as a unit. If a configurable proxy operation specifies any settings in the http_request_transforms structure, the operation-level override will replace all http_request_transforms settings at the API level.

Naming rules

The following table outlines naming rules and character limits for HTTP request transform elements in configurable proxies:

Element Character Limit Permitted Characters
Variable names 63 Variable names: Any except { or }
Variable values 1024 N/A
Rewrite values 1024 N/A
Header names N/A rfc7230
Header values N/A rfc7230
Query parameter names N/A Any (encoded to rfc3986)
Query parameter values N/A Any (encoded to rfc3986)
Path value N/A Any (encoded to rfc3986)

Troubleshooting

This section outlines a number of common error messages you may encounter when validating a configurable proxy archive that uses HTTP request transforms. In most cases, the error message will contain information regarding supported characters, supported values, or syntax issues that can assist in troubleshooting the error.

Validation error messages may include the following:

  • Invalid header name: 
    Header variable reference HEADER_NAME is not a valid header name, supported characters are: …
  • Invalid query parameter name: 
    Query variable reference QUERY_PARAMETER_NAME is not a valid query parameter name, supported characters are: …
  • Undefined path variable reference: 
    Path variable reference VARIABLE_NAME is not defined in path template 'PATH_TEMPLATE_NAME'.
  • Invalid namespace for variable reference: 
    Invalid namespace for variable reference: VARIABLE_NAME; supported values are "path", "header", and "query."
  • Unbalanced curly brackets: 
    Unbalanced curly brackets in PATH_OR_HEADER rewrite.
  • Invalid characters: 
    Invalid character(s) in PATH_OR_HEADER rewrite, supported characters are: …