API Gateway:Create an API

Step 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. 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. Alibaba Cloud App: allows the caller to use an application that passes authentication to call the API. No Authentication: allows all users who are familiar with the request definition of the API to initiate requests. API Gateway directly forwards the request to the backend service without verifying the identity of the caller. We recommend that you do not set Security Certification to No Authentication.
   Signature Algorithm	The algorithm that is used to sign API requests. Valid values: HMAC_SHA256 HMAC_SHA1 and HMAC_SHA256: If you set the parameter to this value, both the algorithms are supported.
   API Option	The feature that you want to grant to the API. Valid values: Anti-replay Protection (X-Ca-Nonce Header Required) Forbid Internet Access Allow API Publish to Alibaba Cloud Marketplace Note If you select Forbid Internet Access and want to apply for a VPC domain name, click Apply for VPC domain name to go to the console.
   Description	The description of the API.

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. Map (Filter Out Unknown Parameters): specifies that you must configure request and response mappings for query, path, and body form parameters. API Gateway transparently passes only the configured parameters to the backend service. Other parameters are filtered out. Map (Pass-through Unknown Parameters): specifies that you must configure request and response mappings for query, path, and body form parameters. API Gateway maps and verifies only the configured request parameters and transparently passes unknown parameters to the backend service. Pass-through: specifies that you do not need to configure query and body form parameters in the request. However, you must configure path parameters. API Gateway transparently passes all parameters that are sent from the client to the backend service.

   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.

   Note

   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.

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
   Configuration Mode	Specifies whether you want to use an existing backend service or customize a backend service. Valid values: Use Existing Backend Service Customize Backend Service
   Backend Service Type	The type of the backend service. Valid values: HTTP/HTTPS Service, VPC, Function Compute, OSS, and Mock. HTTP/HTTPS: This option is selected by default. It indicates that API Gateway accesses the backend service over HTTP or HTTPS. If API Gateway can directly communicate with the backend service, select this option. If you want to use an HTTPS service as the backend service, you must configure an SSL certificate for the HTTPS service. Function Compute: If you want to use Function Compute as the backend service, perform the following operations in advance: Create a function in the Function Compute console, specify a service name and a function name, and then obtain the Alibaba Cloud Resource Name (ARN) of the role for Function Compute. VPC: If the backend service is deployed in a virtual private cloud (VPC), select this option. OSS: If Object Storage Service (OSS) is the backend service, select this option. Mock: If you want to simulate expected results of the HTTP or HTTPS backend service, select this option. 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	The request ID (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.com

If Pass Host Header is disabled, the following host name is received:

Host: apigatewayXXXXXXalicloudapi.com:8080

4. Configure response information

   In the Define Response step, configure Response ContentType, Response Example, Error Response Example, and Error Codes.

Step 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:

1. Find the API that you created, and click the API name or click Manage in the Actions column to go to the Definition page.

2. In the left-side navigation pane, click Debug API.

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

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