All Products
Search
Document Center

API Gateway:Parameter mapping and verification rules

Last Updated:Dec 29, 2023

1. Overview

API Gateway supports parameter mapping and verification. This topic describes the rules that API Gateway uses to process HTTP requests sent from clients and responses returned from HTTP backend services. After processing, API Gateway forwards the requests to backend services and responses to clients. If your backend service is of the Function Compute type, see Use Function Compute as the backend service of an API.

API Gateway supports the following request modes to process request parameters:

  • Pass-through: API Gateway passes parameters in locations except Path to a backend service without mapping and verification. For more information, see section 3.

  • Map (Filter Out Unknown Parameters): API Gateway verifies and maps all parameters in a request based on the API definition. If the request contains an unknown parameter, which is not defined in the API definition, the parameter is filtered out. For more information, see section 4. Map (Filter Out Unknown Parameters).

  • Map (Pass-through Unknown Parameters): API Gateway passes unknown parameters to a backend service. For more information, see section 5. Map (Pass-through Unknown Parameters).

2. Parameter locations and reading rules

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

2.1 path parameters

API Gateway can extract parameters from the segmented paths in HTTP requests. If you want to use path parameters, you must configure the API request path in the /path/[parameter] format. Then, API Gateway matches the path in an HTTP request based on your configured parameter path. The following table shows some examples.

Configured request path

Input data

Extracted data

/request/to/[path]

/request/to/user1

path=user1

/[path1]/[path2].

/group1/user1

path1=group1, path2=user1

/[root]/*

/root/user1

root=root

/[root]

/root/user1

No match

If API Gateway detects input data that does not comply with the RFC 3986 specification, it returns Error code:I400PH: Invalid Request Path. The maximum length of a request URI that API Gateway supports is 128 KB. If a request URI exceeds the maximum length, API Gateway returns Error code:I413RL: Request Url too Large.

2.2 query parameters

query parameters are parameters that are contained in the query string of a request. After receiving a request, API Gateway splits the key-value pairs in the query string of the request by using the equal sign (=) and ampersand (&) and then uses UTF-8 for URL decoding. API Gateway considers both ?a= and ?a as valid values that are equivalent to empty strings enclosed in a pair of double quotation marks (""). The following table shows some examples:

Input data

Extracted data

?a=1&b=2

a: "1", b: "2"

?a=1&a=2

a: ["1", "2"]. If this parameter is of a data type other than ARRAY, only the first value is used.

?a

a: ""

?a=

a: ""

?=a&b=1

b: "1". API Gateway ignores the =a part of the input data.

  • If API Gateway detects input data that does not comply with the RFC 3986 specification, it returns Error code:I400PH: Invalid Request Path.

  • The maximum length of a request URI that API Gateway supports is 128 KB. If a request URI exceeds the maximum length, API Gateway returns Error code:I413RL: Request Url too Large.

2.3 formData parameters

formData parameters are values that are contained in a message body when the Content-Type parameter of a request is application/x-www-form-urlencoded. API Gateway encodes URLs based on the setting of charset=. If no value is specified for charset= in Content-Type, it uses UTF-8 for encoding. API Gateway splits forms in the same way as it splits 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. The following special rules apply when header parameters are processed:

  • Spaces before and after the values of header parameters are truncated.

  • If multiple headers with the same name exist and the parameter type is set to ARRAY, the parameter is parsed as an array. If the parameter type is not set to ARRAY, 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 are valid only after you bind a wildcard domain name to an API group and configure a valid wildcard domain name template. For example, if you bind the wildcard domain name *.api.foo.com to the API group and configure the wildcard domain name template ${user}.api.foo.com, API Gateway reads user=1234 from host parameters when API Gateway receives a request for 1234.api.foo.com. You can configure multiple wildcard domain name templates. API Gateway parses host parameters based on the first matched record. If no record is matched, API Gateway cannot read host parameters. The following table shows some examples.

Configured wildcard domain name template

Request host

Extracted data

${User}.api.io

123.api.io

User: "123"

${User}.${Group}.api.io

123.g01.api.io

User: "123" Group: "g01"

${Admin}.admin.api.io${User}.${Group}.api.io.

123.api.io

User: "123"

${Admin}.admin.api.io${User}.${Group}.api.io

123.admin.api.io

Admin: "123"

${Admin}.admin.api.io${User}.${Group}.api.io

123.u00.api.io

User: "123"GroupId: "u00"

${User}.${Group}.api.io${Admin}.admin.api.io

123.admin.api.io

User: "123"Group: "admin"

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

The passthrough mode supports the following methods: GET, PUT, POST, DELETE, PATCH, HEAD, and OPTIONS.

3.1 Forward client requests to a backend service

In passthrough mode, API Gateway transparently passes requests to a backend service after API Gateway processes the signature and authorization. The following passthrough rules apply to parameters in different locations of a request:

  • path: If you set the API request path to the /path/to/[user] format, you can configure /path/backend/[user] as the backend service path. API Gateway identifies the frontend path parameter and maps the parameter to the backend service path.

  • query string: A query string is transparently passed to the backend service. The sequence and format of the originally received value in the query string remain unchanged.

  • header: Except for specific system headers and headers that start with X-Ca-, API Gateway transparently passes all other headers to the backend service. In addition, API Gateway uses ISO-8859-1 to read and forward the headers. Therefore, if you pass invalid characters in headers, you may receive unexpected results. For information about the processing logic for system and API Gateway reserved headers, see section "6. Processing rules for HTTP headers."

  • Body: API Gateway transparently forwards request bodies to backend services. If you set a custom Content-Type in the API configuration, the custom Content-Type is used. Otherwise, API Gateway forwards a Content-Type header provided by the client.

3.2 Forward backend responses to a client

In passthrough mode, if a backend service returns a response, API Gateway forwards the HTTP response from the backend service to the client. If the processing fails, API Gateway returns an error code. For more information about error codes, see Error codes. The following forwarding rules apply to parameters of different types in a response:

  • Status code: The error code in the response from the backend service is transparently passed.

  • header: API Gateway filters or adds specific system headers and reserved headers that start with X-Ca-. API Gateway passes other headers in the response from the backend service. For more information, see section 6. Processing rules for HTTP headers.

  • body: API Gateway forwards the response body to the client. If Content-Type in the response is empty, API Gateway forwards the default value application/oct-stream.

You can use an error mapping plug-in to change error codes that are returned to clients. For more information, see Plug-ins of the Error Mapping type.

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. If you want API Gateway to forward parameters that are not configured in API definitions to backend services, see section 5. Map (Pass-through Unknown Parameters). This mode supports parameter verification and mapping in the query, header, host, path, and formData locations.

4.1 Parameter types

The following table lists the supported parameter types.

Type

Description

Format

Verification methods

String

Strings

Unlimited

Minimum length, maximum length, enumeration, and regular expression

Integer

32-bit integers

1-1100

Minimum value, maximum value, and enumeration

Long

64-bit integers

-12331001

Minimum value, maximum value, and enumeration

Double

Floating-point numbers

100,0.1,9E-9,1.01E16

Minimum value and maximum value

Boolean

Boolean values

true and false (The value is not case-sensitive.)

File

Files

For multipart/form-data only

Minimum length and maximum length

Array

Arrays

Refer to array field types.

Verification of array field types

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

4.2 Configuration of parameter verification

  • You can configure parameter verification in the API Gateway console, by using OpenAPI Explorer, or by importing a Swagger file. The following table describes the configuration of parameter verification.

Item

Description

Field in OpenAPI Explorer

Field in Swagger

Parameter name

Required. The name must be unique in an API.

ApiParameterName

name

Parameter location

Required.

Location

location

Parameter type

Optional. The default type is STRING.

ParameterType

type

Array field type

Optional. This item is required only if the parameter type is ARRAY.

ArrayItemsType

items.type

Required or not

Optional. The default value is No.

Required

required

The default value.

Optional. An empty string that is enclosed in a pair of double quotation marks ("") is not a valid default value.

DefaultValue

default

Maximum value

Optional. The input value must be less than or equal to the value of this parameter.

MaxValue

maximum

Minimum value

Optional. The input value must be greater than or equal to the value of this parameter.

MinValue

minimum

Maximum length

Optional. This item is valid only if the parameter type is STRING.

MaxLength

maxLength

Minimum length

Optional. This item is valid only if the parameter type is STRING.

MinLength

minLength

Regular expression

Optional. This item is valid only if the parameter type is STRING.

RegularExpression

pattern

Enumeration value

Optional.

EnumValue

enum

Matching rules for parameter verification:

  • OpenAPI Explorer and Swagger have different definitions for parameter types. The description in this topic applies to 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 you set a parameter as required but it is not contained in a request, API Gateway rejects the request and returns the error I400MP Invalid Parameter Requried.

  • You can set default values for optional parameters. If a client does not pass an optional parameter for which you set a default value, API Gateway passes the default value to the backend service. However, API Gateway considers an empty string that is enclosed in a pair of double quotation marks ("") as an invalid default value and does not pass it to the backend service.

  • If a parameter is in the query or formData location and its value is specified in the format of a or a=, for example ?b=1&a, API Gateway considers the input value as an empty string enclosed in a pair of double quotation marks (""). The following items describe how API Gateway handles such an input.

    • 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 value that you specified for the minimum length parameter must be greater than or equal to the required minimum length, and the value that you specified for the maximum length parameter must be less than or equal to the required maximum length. You can configure one of the parameters or both parameters. The parameters take effect only when their configured values are greater than 0.

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

  • Parameters of the STRING and INTEGER types can be specified as enumerated values separated with commas (,), for example, john,jack,tom,tony. If the value is out of the valid value range, API Gateway reports the error I400IP: Invalid Parameter.

  • If the parameter type is set to ARRAY, only the parameters that are located in the query string, body, or header location can be set to arrays. The verification rules for array parameters take effect for each array. The parameter type is specified by the type field of the array parameter, and the default type is STRING.

4.3 Backend mapping rules

  • You can set the Backend Parameter Location and Backend Parameter Name parameters for a parameter. When sending a request to a backend service, API Gateway converts the parameter based on the configured name and location.

  • The parameter types of API Gateway are used only for verification. When a parameter of a specific type is passed to a backend service, the format of the parameter is not changed. For example, If the input value of a parameter of the DOUBLE type is a=1, the value is not changed to a=1.0 when it is passed to the backend service.

  • If the parameter type is ARRAY, the backend location of the parameter can be query string, body, or header. When API Gateway passes such a parameter to a backend service, API Gateway converts the parameter to multiple parameters or multiple headers. For example, API Gateway converts a=1,2 to a=1&a=2.

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

  • If a request contains formData parameters, API Gateway uses application/x-www-form-urlencoded; charset=utf-8 or multipart/formdata; charset=utf-8 to encode the body and sends it to a backend service.

    • If a request contains parameters of the FILE type, API Gateway uses multipart/formdata; charset=utf-8 to assemble the body. Otherwise, API Gateway uses application/x-www-form-urlencoded; charset=utf-8 to assemble the body.

    • If the backend service definition of an API contains a custom Content-Type setting, a request is forwarded based on the custom setting. If the custom Content-Type setting is in the application/x-www-form-urlencoded; charset=??? or multipart/formdata; charset=??? form, the Encoding description in the custom setting is used to assemble the request body. For other Content-Type settings, no special encoding is performed.

  • If the parameter to be forwarded is in the header location, API Gateway uses ISO8859-1 to encode, convert, and forward this parameter.

4.4 Forward backend responses to the client

If a backend service returns a response, API Gateway forwards the HTTP response from the backend service to the client. If the processing fails, API Gateway returns an error code. For more information about how to perform troubleshooting, see Exception handling of API Gateway. The following forwarding rules apply to the parameters of different types in a request:

  • StatusCode: The error code in the response from the backend service is transparently passed.

  • header: API Gateway filters or adds specific system headers and reserved headers that start with X-Ca- and passes other headers in the response from the backend service. For more information, see section 6. Processing rules for HTTP headers.

  • body: API Gateway forwards the response body to the client. If Content-Type in the response is empty, API Gateway forwards the default value application/oct-stream.

You can use an error mapping plug-in to change error codes that are returned to clients. For more information, see Plug-ins of the Error Mapping type.

5. Map (Pass-through Unknown Parameters)

API Gateway filters out unknown parameters in the Map (Filter Out Unknown Parameters) mode and passes unknown parameters in the Map (Pass-through Unknown Parameters) mode. Otherwise, the two modes have the same verification and processing mechanisms.

6. Processing rules for HTTP headers

In most cases, all headers that start with X-Ca- are reserved headers in API Gateway. API Gateway filters out these headers for special processing. Do not start your headers with X-Ca-. Otherwise, your headers are filtered out or your API calls may not be processed as expected.

HeaderName

Processing in request

Processing in response

Connection

Rebuilt

Rebuilt

Keep-Alive

Rebuilt

Rebuilt

Proxy-Authenticate

Rebuilt

Rebuilt

Proxy-Authorization

Rebuilt

Rebuilt

Trailer

Rebuilt

Rebuilt

TE

Rebuilt

Rebuilt

Transfer-Encoding

Rebuilt

Rebuilt

Upgrade

Rebuilt

Rebuilt

Host

Rebuilt

Authorization

Verified and mapped or passed through (If the backend service is an HTTP function, this header is overridden by the Authorization field of the HTTP function.)

Date

Passed through or affixed a default value

Content-Type

Mapped or passed through

Passed through or affixed a default value

Content-Length

Mapped or passed through

Content-MD5

Verified and passed through

Via

Added an API Gateway record

X-Forwarded-For

Affixed to the right the IP address of the client

X-Forwarded-Proto

Added the client request protocol, such as 'http', 'https', 'ws', or 'wss'

User-Agent

Passed through or added an API Gateway UserAgent

Server

Passed through or added a default value

  • No headers marked as rebuilt will be transparently passed. API Gateway adds a defined value for these headers.

  • If the passthrough mode is specified in a request from a client for a header that is not listed in the table, API Gateway transparently passes the header to the backend service. If the mapping mode is specified in the request, all headers except the default HTTP headers are filtered out.

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