All Products
Search
Document Center

API Gateway:Create an API

Last Updated:Nov 14, 2023

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.

  • Alibaba Cloud App: allows the caller to call the API after the app passes the authentication.

  • 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: Only the HMAC_SHA256 algorithm is supported.

  • HMAC_SHA1 and HMAC_SHA256: The HMAC_SHA1 and HMAC_SHA256 algorithms are supported.

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.

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.

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

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

  • HTTP/HTTPS Service: If API Gateway can directly connect to your backend service, select this option. By default, this option is selected. In this case, API Gateway accesses the backend service over HTTP or HTTPS. 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 use Function Compute as the backend service, perform the following operations: 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 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 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.

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
Note

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:

  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.

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.