Parameter mapping and verification rules

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, see 3 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, in transparent 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, see 5 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.

- 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.

• 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.

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 uses ISO-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, see 7 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 custom Content-Type is used. Otherwise, API Gateway forwards a Content-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 and reserved headers that start with X-Ca- and transparently passes other headers in the response from the backend service. For more information, see 7 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 value application/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.

* 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.

• 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 or formData type, API Gateway considers the input value in the format of a or a= 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, or DOUBLE 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 as river,lake,sea. If the input value is not included in the enumerated values, the error code I400IP: Invalid Parameter:... is returned. ``

• If the parameter type is set to ARRAY, only the parameters of the query, formData, or header 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 and backend 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 be query, formData, or header. 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 converts a=1,2 to a=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 or multipart/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 uses multipart/formdata; charset=utf-8 to assemble the package body. Otherwise, API Gateway uses application/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 custom Content-Type is in the application/x-www-form-urlencoded; charset=??? or multipart/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 uses ISO8859-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 and reserved headers that start with X-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 value application/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-.

• 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.