Parameter mapping and verification rules

1. Overview

API Gateway maps, verifies, and forwards HTTP request parameters between clients and backend services. This topic covers the processing rules for each parameter location and request mode. Function Compute backends follow separate rules described in Use Function Compute as the backend service of an API.

API Gateway supports three request modes:

• Pass-through: Forwards all parameters except Path to the backend without mapping or verification (section 3).

• Map (Filter Out Unknown Parameters): Verifies and maps all request parameters based on the API definition. Unknown parameters are filtered out (section 4).

• Map (Pass-through Unknown Parameters): Same as Filter Out mode, but unknown parameters are forwarded to the backend instead of being dropped (section 5).

2. Parameter locations and reading rules

API Gateway reads system parameters, user-configured constant parameters, and parameters from different locations of an HTTP request.

2.1 path parameters

API Gateway extracts parameters from segmented paths in HTTP requests. To use path parameters, configure the API request path in /path/[parameter] format. API Gateway then matches the incoming path against this pattern.

Input data that violates RFC 3986 returns Error code:I400PH: Invalid Request Path. Request URIs exceeding 128 KB return Error code:I413RL: Request Url too Large.

2.2 query parameters

query parameters are extracted from the query string of a request. API Gateway splits key-value pairs by = and &, then applies UTF-8 URL decoding. Both ?a= and ?a are treated as empty strings ("").

• Input data that violates RFC 3986 returns Error code:I400PH: Invalid Request Path.

• Request URIs exceeding 128 KB return Error code:I413RL: Request Url too Large.

2.3 formData parameters

formData parameters are extracted from the request body when Content-Type is application/x-www-form-urlencoded. API Gateway encodes using the charset= value in Content-Type, defaulting to UTF-8. Form splitting follows the same rules as query strings.

If the Content-Type parameter is set to multipart/formdata, API Gateway supports parameters of the FILE type.

2.4 header parameters

header parameters are read from HTTP request headers. For example, X-User: aaa is parsed as X-User=aaa. Special rules:

• Leading and trailing spaces in header values are trimmed.

• If multiple headers share the same name, they are parsed as an array when the type is ARRAY. Otherwise, only the first value is used.

• API Gateway uses ISO-8859-1 encoding to read and forward headers. Invalid characters may cause garbled characters or other unexpected results.

2.5 host parameters

host parameters require a wildcard domain name bound to an API group with a configured template. For example, with template ${user}.api.foo.com, a request to 1234.api.foo.com yields user=1234. Multiple templates are supported; API Gateway uses the first match. Unmatched requests produce no host parameters.

In the last row of the preceding table, ${User}.${Group}.api.io is matched and therefore ${Admin}.admin.api.io is ignored.

3. Pass-through

Pass-through mode supports GET, PUT, POST, DELETE, PATCH, HEAD, and OPTIONS methods.

3.1 Forward client requests to a backend service

In pass-through mode, API Gateway forwards requests to the backend after signature and authorization processing. The following rules apply by parameter location:

• Path: If the API request path uses the /path/to/[user] format, you can map it to a backend path such as /path/backend/[user]. API Gateway extracts the frontend path parameter and maps it to the backend path.

• QueryString: Passed through unchanged, preserving the original sequence and format.

• Header: All headers except system headers and X-Ca--prefixed headers are passed through. API Gateway uses ISO-8859-1 to read and forward headers, so invalid characters may cause unexpected results. System and reserved header processing is described in section 6.

• Body: Forwarded as-is. A custom Content-Type in the API configuration overrides the client-provided value.

3.2 Forward backend responses to a client

In pass-through mode, API Gateway forwards the HTTP response from the backend service to the client. On failure, API Gateway returns an error code. For more information about error codes, see Error codes. Forwarding rules by parameter type:

• StatusCode: Passed through from the backend response.

• Header: API Gateway filters or adds system headers and X-Ca--prefixed reserved headers, then passes all other backend response headers (section 6).

• Body: Forwarded to the client. If Content-Type is empty, defaults to application/oct-stream.

You can use an error mapping plug-in to change error codes that are returned to clients. For more information, see Error code mapping plug-in.

4. Map (Filter Out Unknown Parameters)

In this mode, API Gateway verifies and maps request parameters based on API configurations and filters out unknown parameters. To forward undefined parameters instead, use section 5. This mode supports verification and mapping in the query, header, host, path, and formData locations.

4.1 Parameter types

The following table lists the supported parameter types.

Parameters of the FLOAT type are processed in the same way as parameters of the DOUBLE type.

4.2 Configuration of parameter verification

• Configure parameter verification in the API Gateway console, through OpenAPI Explorer, or by importing a Swagger file.

• OpenAPI Explorer configuration: Front-end input parameters.

• Swagger file import: Import Swagger files to create APIs with API Gateway extensions.

Matching rules for parameter verification:

• OpenAPI Explorer and Swagger define parameter types differently. This topic follows the Swagger standard.

• If you do not set the parameter type, the default type STRING is used.

• If the value is entered in a format other than the supported format, the error I400IP Invalid Parameter is reported.

• If a required parameter is missing from the request, API Gateway returns I400MP Invalid Parameter Requried.

• Optional parameters can have default values. If a client omits such a parameter, API Gateway passes the default to the backend. An empty string ("") is not a valid default value.

• For query or formData parameters specified as a or a= (e.g., ?b=1&a), API Gateway treats the value as an empty string (""):

  • If the parameter is required, no error is returned.

  • If the parameter is optional and a default value is configured for it, API Gateway passes an empty string rather than the default value to the backend service.

• If the parameter type is INTEGER, LONG, FLOAT, or DOUBLE and the input value is an empty string that is enclosed in a pair of double quotation marks (""), the parameter is considered missing.

  • If this parameter is required, API Gateway rejects the request and returns the error 400: <I400MP> Invalid Parameter Requried.

  • If this parameter is optional and has a default value, API Gateway passes the default value to the backend service.

• The minimum length must be greater than or equal to the required minimum, and the maximum length must be less than or equal to the required maximum. You can configure either or both. These constraints take effect only when values are greater than 0.

• The maximum length of a regular expression is 40 characters.

• STRING and INTEGER parameters support enumerated values separated by commas, e.g., john,jack,tom,tony. Out-of-range values return I400IP: Invalid Parameter.

• ARRAY parameters are supported only in query string, body, or header locations. Verification rules apply to each element. The element type defaults to STRING.

4.3 Backend mapping rules

• Set the Backend Parameter Location and Backend Parameter Name to configure how API Gateway maps parameters when forwarding to the backend.

• Parameter types are used for verification only. API Gateway does not change the parameter format when forwarding. For example, a DOUBLE parameter with input a=1 remains a=1 (not converted to a=1.0).

• ARRAY parameters can map to query string, body, or header locations. API Gateway expands arrays into multiple parameters or headers, e.g., a=1,2 becomes a=1&a=2.

• The query string that is passed to a backend service is encoded by using UTF-8 URL encoding.

• For requests with formData parameters, API Gateway encodes the body as application/x-www-form-urlencoded; charset=utf-8 or multipart/formdata; charset=utf-8.

  • Requests with FILE parameters use multipart/formdata; charset=utf-8. All others use application/x-www-form-urlencoded; charset=utf-8.

  • A custom Content-Type in the backend definition overrides the default. If the custom value is application/x-www-form-urlencoded; charset=??? or multipart/formdata; charset=???, the specified charset is used. Other Content-Type values skip special encoding.

• Header parameters are encoded and forwarded using ISO8859-1.

4.4 Forward backend responses to the client

API Gateway forwards the HTTP response from the backend service to the client. On failure, API Gateway returns an error code. Troubleshoot errors using Exception handling of API Gateway. Forwarding rules by parameter type:

• StatusCode: Passed through from the backend response.

• Header: API Gateway filters or adds system headers and X-Ca--prefixed reserved headers, then passes all other backend response headers (section 6).

• Body: Forwarded to the client. If Content-Type is empty, defaults to application/oct-stream.

Use an error mapping plug-in to change error codes returned to clients. Plug-ins of the Error Mapping type.

5. Map (Pass-through Unknown Parameters)

The Map (Filter Out Unknown Parameters) mode discards unknown parameters, while Map (Pass-through Unknown Parameters) mode forwards them to the backend. Both modes share the same verification and mapping logic.

6. Processing rules for HTTP headers

In most cases, all X-Ca--prefixed headers are reserved by API Gateway and filtered for special processing. Do not use X-Ca- prefixes for custom headers, as they will be filtered or may cause unexpected behavior.

• Headers marked as rebuilt are not passed through. API Gateway sets a defined value for them.

• In pass-through mode, unlisted headers are forwarded to the backend. In mapping mode, all headers except default HTTP headers are filtered out.

• By default, all response headers that are not listed in the table are passed through to clients.