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, seesection 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 |
?a | a: "" |
?a= | a: "" |
?=a&b=1 | b: "1". API Gateway ignores the |
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 |
| 123.api.io | User: "123" |
| 123.g01.api.io | User: "123" Group: "g01" |
| 123.api.io | User: "123" |
| 123.admin.api.io | Admin: "123" |
| 123.u00.api.io | User: "123"GroupId: "u00" |
| 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 withX-Ca-
, API Gateway transparently passes all other headers to the backend service. In addition, API Gateway usesISO-8859-1
to read and forward theheaders
. Therefore, if you pass invalid characters in headers, you may receive unexpected results. For information about the processing logic for system and API Gateway reservedheaders
, 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 customContent-Type
is used. Otherwise, API Gateway forwards aContent-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
andreserved headers
that start withX-Ca-
. API Gateway passes other headers in the response from the backend service. For more information, see section6. 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 valueapplication/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 |
| Minimum value, maximum value, and enumeration |
Long | 64-bit integers |
| Minimum value, maximum value, and enumeration |
Double | Floating-point numbers |
| Minimum value and maximum value |
Boolean | Boolean values |
| |
File | Files | For | 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 usingOpenAPI Explorer
, or byimporting 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 | ParameterType | type |
Array field type | Optional. This item is required only if the parameter type is | ArrayItemsType | items.type |
Required or not | Optional. The default value is | Required | required |
The default value. | Optional. An empty string that is enclosed in a pair of double quotation marks ( | DefaultValue | default |
Maximum value | Optional. The input value must be | MaxValue | maximum |
Minimum value | Optional. The input value must be | MinValue | minimum |
Maximum length | Optional. This item is valid only if the parameter type is | MaxLength | maxLength |
Minimum length | Optional. This item is valid only if the parameter type is | MinLength | minLength |
Regular expression | Optional. This item is valid only if the parameter type is | RegularExpression | pattern |
Enumeration value | Optional. | EnumValue | enum |
For information about parameter configuration by using OpenAPI Explorer, see Front-end input parameters.
For information about parameter configuration by importing a Swagger file, see Import Swagger files to create APIs with API Gateway extensions.
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
orformData
location and its value is specified in the format ofa
ora=
, 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
, orDOUBLE
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 beless 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 than0
.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 errorI400IP: Invalid Parameter
.If the parameter type is set to
ARRAY
, only the parameters that are located in thequery string
,body
, orheader
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
andBackend 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 toa=1.0
when it is passed to the backend service.If the parameter type is
ARRAY
, the backend location of the parameter can bequery string
,body
, orheader
. 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 convertsa=1,2
toa=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
ormultipart/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 usesmultipart/formdata; charset=utf-8
to assemble the body. Otherwise, API Gateway usesapplication/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 customContent-Type
setting is in theapplication/x-www-form-urlencoded; charset=???
ormultipart/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 usesISO8859-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
andreserved headers
that start withX-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 valueapplication/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.