DocsICP FilingConsole
官方文档
首页

API definition issues

更新时间：
复制 MD 格式
产品详情
我的收藏

Frequently asked questions about API definitions in API Gateway.

API definition issues

API definition issues

Does API Gateway support gzip data compression, and is it necessary to add the Accept-Encoding request header?

Yes. Responses are compressed if all of the following conditions are met:

  • The request contains the Accept-Encoding header, and its value includes gzip.

  • The response body is larger than 2 KB.

  • The content type of the response body is text/xml, text/plain, text/css, application/javascript, application/x-javascript, application/rss+xml, application/xml, application/json, or application/octet-stream.

How does API Gateway handle undefined parameters?

  • In request parameter mapping (filter unknown parameters) mode, the gateway filters out extra parameters.

  • In request parameter mapping (pass-through unknown parameters) mode and pass-through mode, the gateway passes the parameters through to the backend service.

Can backend services use HTTPS?

Yes. When you enter the backend service endpoint, prefix it with https://. Ensure that your backend service has a valid SSL certificate.

What is a basic API definition?

A basic API definition specifies how the API is accessed, including the protocol (HTTP or HTTPS) and the HTTP method. API Gateway supports all standard HTTP methods.

Why should I enter an API description?

The API description explains the API's features in detail and is displayed to your users.

What are the API types?

APIs can be public or private. If you list a product on Alibaba Cloud Marketplace, public APIs are visible to customers, while private APIs are hidden.

What is an API name?

The API name serves as its identifier. A meaningful name helps users quickly understand the API's purpose.

Is there a delay when updating an API?

No. API updates take effect immediately after publication.

How do I enable HTTPS for my API?

First, request an SSL certificate. Then, bind the certificate to the gateway by going to Group Management, clicking the group name to open the group details page, locating the domain name, and uploading the certificate.

Next, change your API's request protocol to HTTPS or HTTP and HTTPS.

How do I enter a backend service endpoint?

  • The backend service endpoint can be a domain name or an IP address. When you enter it, start with http:// or https://.

  • The backend service endpoint supports dynamic parameters, which are indicated by [param].

    • A backend service endpoint can have multiple dynamic parameters. The names of these dynamic parameters must be unique.

    • Dynamic parameters in the backend service endpoint must be used with dynamic parameters in the path. When you configure the path, configure the mapping to the path.

Why should I define parameters?

Parameters are essential to an API request. API Gateway uses your parameter definitions to generate an API manual for users.

Is parameter definition required?

No, but defining parameters is recommended so that API consumers can clearly understand your API.

How does the gateway handle requests if parameters are not defined?

The gateway processes the request based on the configured request parameter mode.

What does a parameter definition include?

A parameter definition specifies the parameter's location in the request (path, header, query, or body), along with a description, an example, and value constraints.

What constraints can I apply to parameters?

API Gateway supports validation for maximum and minimum values, length, and enumerations. It also supports regular expression and JSON Schema validation.

What is a path?

The path is the fixed portion of the URL that customers use when calling your API. It also serves as an identifier. The combination of HTTP method and path must be unique within the same group.

  • In a RESTful API, the path usually represents a resource in the format of resource/sub-resource, such as instance/disk.

The path supports dynamic parameters, which are indicated by [param], such as instance/disk/[diskid]. These can be mapped to dynamic parameters in the backend service endpoint.

How do I configure dynamic parameters in the path and the backend service endpoint?

When you configure the path, the console can automatically retrieve the dynamic parameters from the backend service endpoint. You only need to map them to the dynamic parameters in the path.

Do the names and order of dynamic parameters in the path and the backend service endpoint have to be the same?

No. You can create a mapping relationship when you configure the path.

What is an APP? How do I associate a user's actual application with a defined APP? Is the actual application a mobile app or a web app?

An APP is a virtual application on Alibaba Cloud that serves as an identity for calling an API. It can be a web application, a mobile application, or another type of application. API Gateway automatically assigns each APP a pair of APP Key and Secret. This pair is used to sign requests to call an API.

How do I specify the environment to call?

When you call an API, the production environment is called by default.

To call the test environment, add the following parameter to the header: X-Ca-Stage: TEST.

To call the pre-release environment, add the following parameter to the header: X-Ca-Stage: PRE.

How do I get error information from API Gateway?

When an API request reaches the gateway, it returns a result.

Check the Header section of the response. Headers that start with X-Ca are returned by the gateway. Important headers include the following:

  • X-Ca-Request-Id: The unique ID of the request. After a request enters API Gateway, the gateway generates a request ID and returns it to the client in the response header. The client and the backend service should both record this request ID for troubleshooting and tracking.

  • X-Ca-Error-Message: The error message returned by API Gateway. When an error occurs, API Gateway returns the error message to the client in the response header.

  • X-Ca-Error-Code: The system error code from API Gateway. When a request is intercepted by the gateway due to an error, API Gateway provides this error code.

You can identify the cause of an error from the X-Ca-Error-Code and X-Ca-Error-Message in the response Header. The X-Ca-Request-Id can be used to query request logs in Simple Log Service, query results in the console, or provide to the helpdesk for log investigation.

For more information about an X-Ca-Error-Code, see the Error Code Table.

How do I disable public network access?

You can disable public network access for an API group so that the APIs are accessible only from the internal network. To do so:

  1. Log on to the API Gateway console. In the navigation pane on the left, choose Open API > Group Management.

  2. In the group list, find the group for which you want to disable public network access and click the group name to go to the details page.

  3. On the group details page, find the Disable Public Network Access button next to the public second-level domain name and click OK to disable public network access.

Important

After you disable public network access, all requests from the public network, including requests to custom public domain names, are rejected. The API can only be called using the internal network domain name.

The API Gateway debug feature does not support debugging for internal network domain names.

The return value of an HTTP/HTTPS request is empty

An HTTP/HTTPS response consists of three parts: HttpCode, Header, and Body. When a request fails, the business logic is not executed, so the Body may be empty. Although this appears as an "empty return value", the important information is in the Header.

If an API request reaches the gateway, the gateway returns either a success or an error result.

The important return information is in the Header. Headers that start with X-Ca are returned by the gateway. The most important headers are listed below:

X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF 
// The unique ID of the request. After a request enters the API Gateway application, API Gateway generates a request ID and returns it to the client in the response header. We recommend that both the client and the backend service record this request ID for troubleshooting and tracking.
X-Ca-Error-Message: Invalid Url  
// The error message returned by API Gateway. When an error occurs, API Gateway returns the error message to the client in the response header.
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}  
// When Debug mode is enabled, debug information is returned. This information may change in the future and is for reference only during joint debugging.

If you send a request and find that the return value is empty, check the returned Header information. If the request fails upon reaching the gateway, it is normal for the Body to be empty. This appears as an empty return value, but the Header will contain important information.

If the Header is also empty, the request did not reach the gateway. Verify your network connection.

You can find methods for obtaining and viewing HTTP/HTTPS header information for various languages online.

HTTPS certificate error

A certificate authentication error occurs, or a message indicates that the certificate has expired, when you call an HTTPS API.

Cause and solutions

  1. Invalid certificate

    The API provider is using a certificate issued by a non-mainstream certification authority (CA). A browser can access the API without issue because browsers automatically update root certificates. However, the root certificates in older operating systems may not trust these CAs, or the trust period may have expired.

    Solutions:

    1. Upgrade the client's root certificate. For example, for Java on Linux, upgrade the OpenSSL client. For other operating systems and programming languages, upgrade the root certificate used for HTTPS in the programming language.

    2. Contact the API provider and ask them to replace the certificate with a more compatible, mainstream SSL Certificate.

    3. In your program, ignore the SSL Certificate validity check (not recommended). Ignoring the check introduces a security risk of request hijacking. Consider this method only if the API provider cannot provide a more compatible, mainstream SSL Certificate and the security risk is manageable.

  2. The API provider's SSL Certificate has expired

    The provider's SSL Certificate has expired.

    Solutions:

    1. Contact the API provider and ask them to replace the SSL Certificate.

    2. In your program, ignore the SSL Certificate validity check (not recommended). Ignoring the check introduces a security risk of request hijacking. Consider this method only if the API provider cannot provide a more compatible, mainstream SSL Certificate and the security risk is manageable.

Cannot connect to the backend service

If you cannot connect to a backend service through API Gateway, troubleshoot as follows:

  • Check whether the backend service endpoint you entered is correct.

  • Ensure that your backend service can be accessed by the gateway.

  • Check the "Backend Timeout" setting in your API definition.

    When you define an API, you must enter a timeout period. If your backend service does not respond within the specified time, API Gateway reports that it cannot connect to the backend service. You can adjust the backend timeout based on the actual response time of your backend service. The maximum timeout is 60,000 ms for Serverless instances and 5 minutes for dedicated instances.

    Note

    The unit is ms (milliseconds).

    The backend timeout cannot be set to 0. For more information about timeout settings, see TCP connection timeout configuration.

  • If the backend service is on an ECS instance, check the security group settings to see if it allows external access. Ensure that the security group allows access from the egress IP address range of API Gateway.

Note that the egress IP addresses used by API Gateway to access external services may change. Security group rules that rely on these IP addresses may break after a change. Instead, we recommend using the backend signature mechanism for identity authentication, which avoids this uncertainty entirely. For more information, see the Backend Signature plug-in document.

How to view the egress IP address of an API Gateway instance:

To find the egress IP address, locate the instance associated with your API group. The steps are:

1. Log on to the API Gateway console. Choose API Management > Group Management > Group Details to view the instance information for the group.

2. Go to the Instances and Clusters page to view the egress address of the corresponding instance.

Previous：API group issuesNext：API call issues