This topic applies only to shared instances and dedicated instances of the VPC type. This topic does not apply to instances of the classic network type.
1. Overview
API Gateway supports parameter mapping and verification. This topic describes the processing rules used when API Gateway forwards client-initiated HTTP requests to an HTTP-based backend service and forwards HTTP responses from the backend service to clients. If the backend service is Alibaba Cloud Function Compute, see Use Function Compute as the backend service of an API operation
API Gateway supports the following transmission modes:
Passthrough mode: In this mode, API Gateway only maps and verifies request parameters of the
path
type and transparently forwards the parameters to the backend service. For more information, see3 Passthrough mode
.Mapping mode: In this mode, API Gateway maps and verifies all user-configured parameters. If a request sent by a client contains a parameter that is not configured, API Gateway does not forward it to the backend service. For more information, see
4 Mapping mode
.Transparent mapping mode: This mode is similar to the
mapping mode
. However, intransparent mapping mode
, if a request sent by a client contains a parameter that is not configured, API Gateway transparently forwards the parameter to the backend service. For more information, see5 Transparent mapping mode
.
2. Locations of parameters and reading rules
API Gateway can read the parameters from different locations of an HTTP request
. API Gateway also supports system parameters
and user-configured constant parameters
.
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 an example.
Configured request path | Input data | Parameter extraction result |
---|---|---|
/request/to/[path] | /request/to/user1 | path=user1 |
/[path1]/[path2]. | /group1/user1 | path1=group1, path2=user1 |
/[root]/* | /root/user1 | root=request |
/[root] | /root/user1 | No match. |
- If API Gateway detects invalid 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 the values contained in QueryString
of requests. After API Gateway receives a request, it splits the key-value pairs in QueryString
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 single quotation marks ('
). The following table shows an example.
Input data | Parameter extraction result |
---|---|
? 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 invalid 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 the values contained in the message body when Content-Type
of a request is application/x-www-form-urlencoded
. If charset
in Content-Type
is not specified, API Gateway uses UTF-8
encoding. If charset
is specified, API Gateway uses the specified character set for URL decoding. API Gateway splits and processes formData parameters in the same way as splitting and processing QueryString
.
If Content-Type
is 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 processing of header parameters has the following special rules:
Both the spaces before and after the values of header parameters are removed.
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 if you have bound domain names to a wildcard domain name and added a valid wildcard domain name template. For example, if you bind the wildcard domain name *.api.foo.com
and configure the wildcard domain name template ${user}.api.foo.com
, API Gateway reads user
=1234
from the host
parameters when it 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 obtain the host
parameters. The following table shows an example.
Configuration of a template for a wildcard domain name | Request host | Parameter extraction result |
---|---|---|
| 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. Passthrough mode
The passthrough mode supports the following methods: GET
, PUT
, POST
, DELETE
, PATCH
, HEAD
, OPTIONS
.
3.1 Forward client requests
to the backend service
In passthrough mode, API Gateway transparently passes requests to the backend service after it 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 also configure/path/backend/[user]
as the backend service path. API Gateway identifies the frontend path parameter and maps it to the backend service path.QueryString: Data of this type is transparently passed to the backend service. The sequence and format of the originally received value of QueryString remain unchanged.
Header: API Gateway transparently passes all headers except for some system headers and headers that start with
X-Ca-
to the backend service and usesISO-8859-1
encoding to read and forward these headers. Therefore, if an invalid encoding is passed in a header, an error may occur. For more information about the processing logic of the headers that API Gateway reserve, see7 HTTP header processing rules
.
Body: API Gateway transparently forwards the package body to the backend service. 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 the client
In passthrough mode, if the backend service returns a response, API Gateway forwards the HTTP response
from the backend service
to the client
. If the backend service fails to return a response, API Gateway generates an error code. For more information about how to perform troubleshooting, see Error code table The following passthrough 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
system headers
andreserved headers
that start withX-Ca-
and transparently passes other headers in the response from the backend service. For more information, see7 HTTP header processing rules
.Body: API Gateway forwards the package body in the response from the backend service to the client. If
Content-Type
in the response is empty, API Gateway forwards the default valueapplication/oct-stream
.
You can use the Plug-ins of the Error Mapping type plug-in to change the HTTP status codes in the responses from the client.
4. Parameter mapping mode
In parameter mapping mode
, API Gateway verifies and maps the parameters that you have configured. If the client passes a parameter that is not configured, API Gateway does not forward the parameter to the backend service. If you want API Gateway to forward parameters that are not configured to the backend service, see 5 Transparent mapping mode
. In parameter mapping mode, API Gateway supports the parameters of the query
, header
, host
, path
, and formData
types. API Gateway can also determine and verify the types of parameter values and forward the parameters to the backend service.
4.1. Parameter types
The following table lists the parameter types that API Gateway supports.
Type | Description | Supported format | Verification method |
---|---|---|---|
String | STRING | Unlimited | Minimum length, maximum length, enumerated value, and regular expression |
Integer | A 32-bit integer |
| Minimum, maximum, and enumerated values |
Long | A 64-bit integer |
| Minimum, maximum, and enumerated values |
Double | Floating point |
| Minimum and maximum values |
Boolean | BOOLEAN |
| |
File | File type | For | Minimum length and maximum length |
Array | ARRAY | See the array field type. | 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
, orby importing a Swagger file
. The following table describes the configuration of parameter verification.
Parameter verification item | Description | Field on OpenAPI Explorer | Field in Swagger |
---|---|---|---|
Param Name | Required. The name must be unique in an API operation. | ApiParameterName | name |
Param Location | Required. | Location | location |
Type | Optional. The default type is | ParameterType | type |
Type Of Array Field | Optional. This parameter is required only if the parameter type is | ArrayItemsType | items.type |
Required | Optional. The default value is | Required | required |
Default Value | Optional. An empty string enclosed in a pair of single quotation marks ( | DefaultValue | default |
Max | Optional. The input value must be | MaxValue | maximum |
Min | Optional. The input value must be | MinValue | minimum |
Max Length | Optional. This parameter is valid only if the parameter type is | MaxLength | maxLength |
Min Length | Optional. This parameter is valid only if the parameter type is | MinLength | minLength |
Param Verification | Optional. This parameter is valid only if the parameter type is | RegularExpression | pattern |
Enumeration | Optional. | EnumValue | enum |
For more information about the parameter configuration on OpenAPI Explorer, see Front-end input parameters
For more information about parameter configuration on Swagger, see Import Swagger files to create APIs
Matching rules for parameter verification:
OpenAPI Explorer and Swagger have different definitions for parameter types. The description in this topic is subject to the
Swagger
standard.If you do not set the parameter type, the default type
String
is used.If the input format of the parameter type is inconsistent with the format supported by the current type, the error code
I400IP Invalid Parameter: ...
is reported. ``If a request of the client does not contain a required parameter, API Gateway blocks the request and returns the error code
I400MP Invalid Parameter Required: ...
. ``You can set default values for optional parameters. If the 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 enclosed in a pair of single quotation marks (
'
) as an invalid default value and does not pass it to the backend service.If a parameter is of the
query
orformData
type, API Gateway considers the input value in the format ofa
ora=
such as? b=1&a
as an empty string enclosed in a pair of single quotation marks ('
).If the parameter is required, no error is returned.
If the parameter is optional and a default value is configured, API Gateway passes an empty string rather than the default value to the backend service.
If the parameter type is
INTEGER
,LONE
,FLOAT
, orDOUBLE
and the input value is an empty string enclosed in a pair of single quotation marks ('
), the parameter is considered not passed.If this parameter is required, API Gateway blocks the request and returns the error code
400: <I400MP> Invalid Parameter Required: ...
.If this parameter is optional and has a default value, API Gateway passes the default value to the backend service.
Min Length and Max Length take effect only when its configured value is greater than
0
.The maximum length of a regular expression is 40 characters.
Parameters of both the STRING and NUMERIC types can be set to
enumerated values
. The enumerated values must be separated with commas (,), such asriver,lake,sea
. If the input value is not included in the enumerated values, the error codeI400IP: Invalid Parameter:...
is returned. ``If the parameter type is set to
ARRAY
, only the parameters of thequery
,formData
, orheader
type can be set to arrays. The verification rules for array parameters take effect for each array. The parameter type is specified by the type of the array parameter, and the default type is STRING.
4.3. Parameter mapping rules of backend services
You can set the
backend location
andbackend name
for parameters. API Gateway converts the parameter location and name when it sends requests to the backend service.If the parameter type is
ARRAY
, the backend location can only bequery
,formData
, orheader
. When API Gateway passes such a parameter to the backend service, API Gateway converts the parameter to multiple parameters or multiple headers. For example, it convertsa=1,2
toa=1&a=2
.The QueryString that is passed to the backend service is encoded by using
UTF-8 and URL encoding
.If the parameters in a request include formData parameters, API Gateway uses
application/x-www-form-urlencoded; charset=utf-8
ormultipart/formdata; charset=utf-8
to encode the package body and sends it to the backend service.If the parameters in a request contain parameters of the
FILE
type, API Gateway usesmultipart/formdata; charset=utf-8
to assemble the package body. Otherwise, API Gateway usesapplication/x-www-form-urlencoded; charset=utf-8
to assemble the package body.If you configure a custom
Content-Type
in the Define API Backend Service step, API Gateway sends the custom Content-Type to the backend service. If the customContent-Type
is in theapplication/x-www-form-urlencoded; charset=???
ormultipart/formdata; charset=???
format, API Gateway uses the encoding format specified in ContentType Value to assemble the package body.
If the parameter to be forwarded is of the
header
type, API Gateway usesISO8859-1
to convert and forward this parameter.
4.4. Forward backend responses
to the client
In parameter mapping mode, if the 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 Error code table 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
system headers
andreserved headers
that start withX-Ca-
and transparently passes other headers in the response from the backend service. For more information, see 5 Header forwarding rules.Body: API Gateway forwards the package body in the response from the backend service to the client. If
Content-Type
in the response is empty, API Gateway forwards the default valueapplication/oct-stream
.
You can use the Plug-ins of the Error Mapping type plug-in to change the HTTP status codes in the responses from the client.
5. Passthrough mapping mode
The verification and processing mechanisms for the passthrough mapping mode
and parameter mapping mode
are similar. The only difference is that unknown parameters in a request are transparently passed to the backend service in passthrough mapping mode
. Whereas, the unknown parameters are filtered out in parameter mapping mode
.
6. Strict mapping mode
The verification and processing mechanisms for the strict mapping mode
and parameter mapping mode
are similar. The only difference is that an error is reported if a request contains unknown parameters in strict mapping mode
.
7. HTTP header processing rules
In normal cases, all headers that start with X-Ca-
are reserved headers in API Gateway. API Gateway filters out these headers or performs special processing. Do not use headers that start with X-Ca-
.
HeaderName | Request processing method | Response processing method |
---|---|---|
Connection | Rebuild | Rebuild |
Keep-Alive | Rebuild | Rebuild |
Proxy-Authenticate | Rebuild | Rebuild |
Proxy-Authorization | Rebuild | Rebuild |
Trailer | Rebuild | Rebuild |
TE | Rebuild | Rebuild |
Transfer-Encoding | Rebuild | Rebuild |
Upgrade | Rebuild | Rebuild |
Host | Rebuild | N/A |
Authorization | Verify, map, or pass through | N/A |
Date | N/A | Pass through or add a default value |
Content-Type | Map or pass through | Pass through or add a default value |
Content-Length | Map or pass through | N/A |
Content-MD5 | Verify and pass through | N/A |
Via | Add records of API Gateway | N/A |
X-Forwarded-For | Add the IP address of the client to the right of the existing value | N/A |
X-Forwarded-Proto | Add a client request protocol: 'http', 'https', 'ws', or 'wss' | N/A |
User-Agent | Pass through or add a UserAgent of API Gateway | N/A |
Server | N/A | Pass through or add a default value |
All the headers marked as rebuild will not be transparently passed and API Gateway adds a defined value for these headers.
If the passthrough mode is specified in a request from the 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, the headers of responses that are not listed in the table are transparently passed to the client.