This topic describes how to create and debug an API and add security configurations to the API. To create an API, you must configure the basic information, request information, backend service, and response information for the API. After the API passes the debugging test, you can publish the API for users to call.
1. Configure an API
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > APIs. On the APIs page, click Create API to create and configure an API.
1.1 Configure basic information
Parameter | Description |
API Group | The basic management unit of APIs. Before you create an API, you must create an API group. When you select a group, a region is selected for the API. |
API Name | The name of the API to be created. Each API name in an API group must be unique. |
Security Authentication | Currently, Alibaba Cloud App and No Authentication are supported.
|
Signature Algorithm | The algorithm that is used to sign API requests. Valid values:
|
Description | The description of the API. |
1.2 Configure request information
In the Define API Request step, configure the request information about the API. The detailed configurations include Protocol, Request Path, HTTP Method, Request Mode, and Request Parameters.
Parameter | Description |
Protocol | The network protocol that is used for the API request. Valid values: HTTP and HTTPS. |
Request Path | The API request path that corresponds to the service host. The request path can be different from the actual backend service path. You must specify a valid and semantically accurate path as the request path. You can configure dynamic parameters in the request path. This requires that you specify path parameters in the request. In addition, the path parameters can be mapped to query and header parameters that are received by the backend service. |
HTTP Method | The standard HTTP request method. Valid values: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS, and ANY. |
Request Mode | The mode in which request parameters are passed. Valid values: Request Parameter Map (Filter Out Unknown Parameters), Map (Pass-through Unknown Parameters), and Pass-through.
|
Configure request parameters: In the Request Parameters section, configure the request parameters of the API in specific locations. The following locations are supported: Parameter Path, Head, and Query. When you configure a dynamic path parameter, you must provide a description for the dynamic parameter. The following data types are supported: String, Int, and Boolean.
The names of all parameters must be unique.
You can use the shortcut keys in the No. column to change the order in which parameters are arranged.
You can click Remove in the Actions column to remove a parameter that you no longer require.
If you have configured a dynamic parameter in the request path, you must define a parameter with the same name as the dynamic parameter and set Parameter Location to Parameter Path.
Configure a parameter verification rule: Find the parameter for which you want to configure a verification rule and click Advanced Settings in the Actions column. In the Advanced Settings dialog box, configure relevant parameters, such as Maximum Length and Enumerated Value. API Gateway pre-verifies requests based on the verification rules. Requests with invalid parameters are not sent to your backend service. This significantly reduces the workload on your backend service.
1.3 Configure a backend service
In the Define Backend Service step, configure the request and response mappings for parameters and specify the API configurations of your backend service. After API Gateway receives a request, it converts the format of the request into the format that is required by your backend service based on the backend service configuration. Then, API Gateway forwards the request to your backend service.
Configure basic information: In the Basic Settings for Backend Service section, configure the basic information about the backend service.
Parameter | Description |
Backend Service Type | The type of the backend service. Valid values: HTTP/HTTPS Service, VPC, Function Compute, OSS, and Mock.
Note You cannot create a backend service of the HTTP or OSS type in regions outside China or in the China (Hong Kong) region. |
VPC Access Name | If your backend service is deployed in a VPC, specify a VPC access authorization name. |
Backend Service URL | The host URL of the backend service. The value can be a domain name or a value in the http://host:port or https://host:port format. The value must start with http:// or https://. |
Backend Request Path | The actual request path of your API on your backend server. If you want to receive dynamic parameters in the backend service path, you must declare parameter mappings by specifying the locations and names of the relevant request parameters. |
HTTP Method | The standard HTTP request method. Valid values: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS, and ANY. |
Backend Service Timeout Period | The time allowed for API Gateway to send a received API request to the backend service and receive a response from the backend service. The response time starts from the time when API Gateway sends an API request to the backend service and ends at the time when API Gateway receives a response from the backend service. The response time cannot exceed 30s. If API Gateway does not receive a response from the backend service within 30s, API Gateway stops accessing the backend service and returns an error message. |
Configure backend service parameters: In the Backend Service Parameters section, configure request and response mappings for parameters. Name mappings and location mappings are supported. API Gateway can map a path, header, query, or body request parameter to a response parameter at a different location. This way, you can package your backend service into a standardized and professional API form. This part declares the mappings between request and response parameters.
Configure constant parameters: In the Constant Parameters section, configure constant parameters. Constant parameters are invisible to your users. After API Gateway receives requests, it adds constant parameters to specified locations in the requests and forwards the requests to your backend service to suit your business needs on the backend service. If you want API Gateway to attach the abc parameter to each request that API Gateway forwards to your backend service, you can configure the abc parameter as a constant parameter. After API Gateway receives a request, API Gateway adds the abc parameter to the specified location and forwards the request to your backend service.
Configure system parameters: In the System Parameters section, configure the system parameters that are supported by API Gateway. By default, API Gateway does not add system parameters to API requests. If you want to obtain the system parameters, you can configure their locations and names. The following table lists the system parameters:
Parameter | Description |
CaClientIp | The IP address of the client that sends an API request. If you have configured Web Application Firewall (WAF) or Content Delivery Network (CDN), the system records the back-to-origin IP address. The real IP address of the client is recorded in X-Forwarded-For. |
CaDomain | The domain name that is used to send an API request. |
CaRequestHandleTime | The request time in UTC. |
CaRequestId | RequestId |
CaApiName | The API name. |
CaHttpSchema | The protocol that is used to call the API. Valid values: HTTP and HTTPS. |
CaProxy | The proxy that is used to handle an API request. Set the value to AliCloudApiGateway. |
CaClientUa | The user agent of the client that sends an API request. |
CaCloudMarketInstanceId | The ID of the instance that corresponds to the Alibaba Cloud Marketplace commodity that is purchased for the first time. |
CaAppId | The ID of the application that is used to call the API. |
CaAppKey | The key of the application that is used to call the API. |
CaAppExtendInfo | The extensions of the application. |
CaStage | The environment in which you call the API. Valid values: RELEASE, TEST, and PRE. |
CaInstanceId | The ID of the instance to which the API belongs. |
CaSourceVpcId | The VPC to which the client IP address belongs. |
You can select Pass Host Header in the Request Header Pass-through Settings section of the API group details page. After you select Pass Host Header, API Gateway passes the Host header parameter in the request to the backend service. If you do not select Pass Host Header, API Gateway sends the Host header that you specify to the backend service. The following code shows an example:
For example, if you attach the xuemeng.XXXX.com host name to an API group, the host name of the backend service of APIs in the API group is apigatewayXXXXXXalicloudapi.com:8080. The following code snippets show the different host names that are received by your backend service before and after Pass Host Header is enabled.
If Pass Host Header is enabled, the following host name is received:
Host: xuemeng.XXXX.comIf Pass Host Header is disabled, the following host name is received:
Host: apigatewayXXXXXXalicloudapi.com:8080When you configure parameters for the backend service of the API, make sure that the name of each parameter is globally unique in API Gateway. This applies to dynamic path parameters, header parameters, query parameters, non-binary body parameters, constant parameters, and system parameters. For example, if you specify name as the names of a header parameter and a query parameter, an error occurs.
1.4 Configure response information
In the Define Response step, configure Response ContentType, Response Example, Error Response Example, and Error Codes.
2. Debug the API
After you create and configure the API, you can debug the API on the API debugging page to ensure that the API works as expected.
After the API is created and configured, you are redirected to the APIs page. On this page, perform the following operations to check whether the API can be called and whether the request URL is valid:
Find the API that you created, and click the API name or click Manage in the Actions column to go to the Definition page.
In the left-side navigation pane, click Debug API.
On the page that appears, specify request parameters in the Request Parameters section and click Send Request.
A result appears on the right side of the page.
If a success response is returned, the API is called as expected.
If an HTTP 4XX or 5XX status code is returned, an error occurred when the API is called. For more information, see How to obtain the error message and Error codes.
3. What to do next
After you configure and debug the API, the API is available for calls. You can publish the API to the test, staging, or production environment for further debugging or for users to call. You can also add security configurations to the API. For example, you can attach a signature for the API. For more information, see Use digest authentication to call an API.