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 OpenAPI > APIs. On the APIs page, click Create API to create and configure an API.
1.1 Configure basic information
Parameter | Description |
API Group | The API group is the basic unit that is used to manage APIs. Before you create an API, create an API group. When you select an API group, the region in which the API group resides is used for the API. |
API Name | The name of the API that you want to create. Each API name in an API group must be unique. |
Security Authentication | The mode in which security authentication is performed. Valid values: Alibaba Cloud App and No Authentication.
|
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, HTTPS, and WEBSOCKET. |
Request Path | The API request path that corresponds to the service host. The request path can be different from the actual path of your backend service. The request path that you specify must be valid and semantically accurate. If you want to configure dynamic parameters in the request path, you need to only specify dynamic path parameters in the request. 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: 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 included: 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 rule. Requests that contain 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 requests, it converts the format of the requests into the format that is required by your backend service based on the configurations of the backend service, such as the URL, path, timeout period, constant parameters, and system parameters. Then, API Gateway forwards the requests 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 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 response time for API Gateway to access the backend service of the API after API Gateway receives an API request. 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 that is defined at a different location. This allows you to package your backend service into a standardized and professional API form.
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 describes 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. |
CaAppId | The ID of the app from which an API request is sent. |
CaRequestId | RequestId |
CaApiName | The name of the API. |
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. |
CaCloudMarketInstanceld | The ID of the instance that corresponds to the Alibaba Cloud Marketplace commodity that is requested. |
CaAppKey | The key of the app from which an API request is sent. |
CaStage | The environment in which you call the API. Valid values: RELEASE, TEST, and PRE. |
You can configure Pass Host Header for a shared instance on the Group Details page of an API group. If you want to configure Pass Host Header for a dedicated instance, submit a ticket to enable the feature. After the feature is enabled, API Gateway transparently passes the domain name of an API request to your backend service. If you do not enable the feature, API Gateway passes the host name that you specified in API Gateway to your backend service. 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 figures 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.
If Pass Host Header is disabled, the following host name is received.
When 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 section, 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 created. 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.