This topic provides answers to some frequently asked questions (FAQ) about API definitions in API Gateway.
API definition issues
API definition issues
Does API Gateway support gzip compression and do I need to add the Accept-Encoding request header?
Yes. A response is compressed when the following three conditions are all met:
The request carries the Accept-Encoding header, and the value of this field contains gzip.
The response body is greater than 2 KB in size.
The contenttype value in the response body is text/xml text/plain text/css application/javascript application/x-javascript application/rss + xml application/xml application/json application/octet-stream.
How does API Gateway handle an undefined parameter?
If the Request Mode parameter of the API is set to Map (Filter Out Unknown Parameters), API Gateway filters out the undefined parameter.
If the Request Mode parameter of the API is set to Map (Pass-through Unknown Parameters), API Gateway passes the undefined parameter to the backend service.
Can I select HTTPS as the backend service type?
Yes. When you enter the backend service URL, you must start with https:// and make sure that your backend service has a Secure Sockets Layer (SSL) certificate.
What is the basic definition of an API?
The basic definition defines how you want your API to be accessed, such as the protocol (HTTP or HTTPS) and the HTTP method. API Gateway supports all standard HTTP methods.
Why is a description required for an API?
Using the description, you can show callers what your API can do.
Into what types are APIs categorized?
APIs can be public or private. Public APIs are available in Alibaba Cloud Marketplace for use in commodities therein. Private APIs are not displayed in Alibaba Cloud Marketplace.
What is an API name?
API names are the identifiers of the APIs. A meaningful name allows callers to understand the functionality of your API at a glance.
How long does it take for an API update to take effect?
An API update takes effect immediately once the API is published.
How do I enable my API to support HTTPS?
First, you need to apply for an SSL certificate and associate it with the API group to which your API belongs. Then, change the request protocol from HTTP to HTTPS for your API. To associate the certificate, click your API group, find the target domain name, and upload the certificate.
How do I specify a backend service URL?
A backend service URL can be a domain name or an IP address. However, you must prefix it with http:// or https:// when you specify it.
Dynamic parameters are supported in such URLs and indicated with [param].
Multiple dynamic parameters are supported in a URL. The parameter names must be unique.
The dynamic parameters work together with the dynamic parameters in path. When you configure path, you must configure dynamic parameter mappings between path and the URL.
Why do I need to define parameters?
Parameters are an important part of an API request. API Gateway can generate API documentation based on parameter definitions to help callers understand your API.
Is parameter definition required?
No, but we recommend that you do it to help callers understand your API.
What happens if I do not define any parameter?
In this case, request parameters are filtered out or passed through based on the configured request mode.
What does a parameter definition define?
The location of the parameter in a request, such as path, header, query, or body, the parameter description, parameter sample, and value range.
What limits can I define for a parameter?
The maximum value, minimum value, value length, enumerated values, regular expression, and JSON schema of the parameter.
What is a path?
path is a section of a request. This section specifies the fixed path of an API that is displayed to the caller. path is another identifier of the API. The HTTP method and path combination of an API must be unique in an API group.
For RESTful APIs, the path also indicates resources in the format of resource/child resource. Example: instance/disk.
The path section of a request supports dynamic parameters, which are indicated by [param] (example: instance/disk/[diskid]) and mapped to dynamic parameters in backend service URLs.
How do I configure dynamic parameters in path and backend service URLs?
When you configure path, the console automatically displays the dynamic parameters in the URL of the backend service. What you need to do is map them.
Is it necessary to keep path parameters consistent with the dynamic parameters in the backend service URL in terms of name and sequence?
No, you map the parameters when you configure path.
What is an application, how is an actual application related to an application in API Gateway, and does the actual application run on a mobile device or a web browser?
An application is a virtual identity that an API caller assumes to call your API. An application can be a web application, mobile application, or an application in another form. API Gateway assigns an AppKey and AppSecret pair to each application. This pair is used to sign requests to call APIs.
How do I specify an environment to call an API?
By default, APIs are called in the production environment.
To call an API in the test environment, add the X-Ca-Stage:TEST header to the request.
To call an API in the staging environment, add the X-Ca-Stage:PRE header to the request.
How do I obtain error messages?
API Gateway returns a response for each request received.
To obtain error messages, go for the header section of the response. Headers starting with X-Ca are returned by API Gateway. Take note of the following points:
X-Ca-Request-Id: the unique ID of the request. When API Gateway receives a request, it generates a request ID and returns the request ID in the X-Ca-Request-Id header. We recommend that you record the request ID in both the client and your backend service for troubleshooting and tracing purposes.X-Ca-Error-Message: the error message returned by API Gateway.X-Ca-Error-Code: the system error code. This header is returned if the request has an error and is rejected by API Gateway.
The X-Ca-Error-Code and X-Ca-Error-Message headers help you identify the error cause. The X-Ca-Request-Id header helps you query request logs in Simple Log Service. You can also provide the request ID included in the X-Ca-Request-Id header for technical support personnel to check log information and resolve issues.
For more information about X-Ca-Error-Code, see Error codes.
How do I disable public access?
If you do not want your APIs to be called over the Internet, you can disable public access for the API group to which your APIs belong. This way, callers can call your APIs only over a virtual private cloud (VPC). To do this, perform the following steps:
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups.
Click the API group that you want to manage on the API Groups page. The Group Details page appears.
In the Basic Information section, find the public second-level domain name of the API group and click Disable Access over Internet on the right.
After you disable access over the Internet, all requests from the Internet, including those from custom domain names, are denied, and API calls have to be initiated from internal domain names.
Take note that the API Gateway console does not support API debugging based on internal domain names.
What do I do if an empty HTTP/HTTPS response is received?
An HTTP/HTTPS response consists of three parts: an HTTP code (HttpCode), headers (Header), and a body (Body). When an error occurs in a request, the request is not processed by the business logic. As a result, an empty response is returned. However, the response contains important information in its headers.
API Gateway returns a success or error message to the client as long as a request is received.
Response headers contain important information, especially headers starting with X-Ca. The following code shows some important headers:
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
//the unique ID of the request. When API Gateway receives a request, it generates a request ID and returns the request ID in the X-Ca-Request-Id header. We recommend that you record the request ID in both the client and your backend service for troubleshooting and tracing purposes.
X-Ca-Error-Message: Invalid Url
//the error message returned by API Gateway. If a request fails, API Gateway returns the error message in the X-Ca-Error-Message header.
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
// The message returned only when the debug mode is enabled. The message is used only for reference at the debugging stage.Therefore, if you receive an empty response, check its headers. If the body is empty but headers are not, the request is received by API Gateway.
If both the body and headers are empty, the request is not received by API Gateway. In this case, check your network connection.
You can search on the Internet for methods to obtain HTTP/HTTPS headers in different programming languages and select a method based on your business requirements.
What do I do if an HTTPS certificate error is reported?
Symptom: The system prompts that a certificate authentication error occurs or the certificate is expired when you call an API over HTTPS.
Causes and solutions
The certificate is invalid.
The certificate used by the API provider is issued by a non-mainstream organization. Such a certificate can be used for general web browsing because the browser automatically updates the root certificate. However, root certificates in operating systems (OSs) of earlier versions do not trust the organization or the trust has expired.
Solution:
Update the root certificate. If you are using a Java client in a Linux OS, upgrade the OpenSSL client. For other OSs and languages, update the root certificate used for HTTPS based on the actual situation.
Contact the API provider to replace the certificate with a mainstream SSL certificate that provides wider compatibility.
Configure your program to skip SSL certificate validity check. This solution is not recommended due to subsequent hijacking risks. This solution can be considered only when security risks are under control and the API provider fails to provide a mainstream SSL certificate.
The certificate is expired.
The certificate of the API provider has expired.
Solutions:
Contact the API provider to replace the certificate.
Configure your program to skip SSL certificate validity check. This solution is not recommended due to subsequent hijacking risks. This solution can be considered only when security risks are under control and the API provider fails to provide a mainstream SSL certificate.
What do I do if the backend service does not respond to a request?
Troubleshoot the issue by performing the following operations:
Check whether the URL of the backend service is correct.
Check for connectivity issues between API Gateway and your backend service.
Check the backend service timeout period in the API definition.
When you create an API, you are required to specify a backend service timeout period. If your backend service does not return a response within the specified period, API Gateway prompts you that the backend service cannot be connected. You can specify a timeout period based on the time required by the backend service to process a request. You can set a period up to 300,000 ms (5 minutes) for an API on a dedicated instance.
NoteTake note that the unit of the timeout period is milliseconds (ms).
You cannot set the timeout period to 0. For more information about the timeout period, see Configure timeout periods for TCP connections.
If your backend service is deployed on an Elastic Compute Service (ECS) instance, check the security group settings on the ECS instance to make sure that the instance can be accessed from the egress CIDR block of your API Gateway instance.
Take note that the egress IP address of an API Gateway instance changes. As a result, the ECS instance denies access if the new egress IP address is not allowed access by the security group settings on the ECS instance. Therefore, we recommend that you use the backend signature verification mechanism provided by API Gateway to authenticate caller identities. This mechanism eliminates such risks. For more information, see Backend signature plug-ins.
View the egress IP address of an API Gateway instance:
Perform the following steps to view the egress IP address:
1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups. Then, click the desired API group and record the ID of the instance on which the group resides on the group details page.
2. On the left-side navigation pane, choose Instances and Clusters > Shared Instances or Instances and Clusters > Dedicated Instances based on your instance type to view the egress IP address of your instance.