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 ( |
Variables | Variable references are enclosed in curly brackets: {example} .
All variable references must begin with a valid namespace (characters + 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 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 Only valid header names can be used. Pseudo headers (eg. headers starting with |
{query.query_parameter_name} |
Query parameter values can be referenced by name in the 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
orheaders.remove
objects are always removed before values contained in thequery.remove
orheaders.remove
objects are added. - Values in the
name
fields are case insensitive. - The resulting values of
add
andremove pairs
are delivered as separate elements, such as as multiple query parameters in thepath
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: …