All Products
Search
Document Center

API Gateway:Create an API operation with a resource in a VPC as the backend service

Last Updated:Dec 12, 2022

This topic describes how to create and publish an API operation with a resource in a VPC as the backend service in API Gateway, and how to call the API operation in an app by using an AppCode. The AppCode is automatically generated for the app when you set the authentication method of the API operation to Alibaba Cloud App.

Overview

You must perform the following steps in sequence:

  • Authorize API Gateway to access a VPC

  • Create a group

  • Create and define an API operation

  • Create an app and grant the app the permissions to call the API operation

  • Allow outbound IP addresses of API Gateway in a security group

  • Debug the API operation

  • Call the API operation

1. Create instances in a VPC.

Purchase and create Server Load Balancer (SLB) and Elastic Compute Service (ECS) instances in a VPC.

In this example, an ECS instance in a VPC is used as the backend service of an API operation. The ECS instance is deployed in NGINX and uses port 80 for communication. Web services are deployed on the ECS instance.

2. Authorize API Gateway to access the VPC

Step 1 Create a VPC access authorization

To allow API Gateway to access a VPC, you must create a VPC access authorization.

In the left-side navigation pane of the API Gateway console, choose Open API > VPCs. On the VPC Access Authorizations page, select the region where the VPC resides and click Create Authorization. In the Create VPC Access dialog box, specify VPC Access Name, VPC Id, Instance ID or IP Address, and Port Number. If you need to specify a domain name to access a vhost on an SLB instance or ECS instance, you can specify the domain name as Host.

Create a VPC access authorization

In VPC Id, enter the ID of the VPC where your backend service resides. In Instance ID or IP Address, enter the ID or private IP address of the instance where your backend service resides. You can obtain the information in the instance details.

vpcid

Note
  • For Application Load Balancer (ALB) instances, the network type must be VPC, and you cannot change the network type to Internet after you create the authorization. Otherwise, requests may fail to be sent to API Gateway, and you are responsible for the consequences.

  • When you create an authorization for an ALB instance, make sure that the version of API Gateway is 3.5.3.706 or later. Otherwise, the configurations do not take effect. If the configurations do not take effect, submit a ticket to upgrade the service version.

3. Create an API group

API operations are managed in API groups. Before you create an API operation, you must create an API group.

Step 1: Create an API group.

Log on to the API Gateway console. In the left-side navigation pane, choose Open API > API Groups. Select a region in the top navigation bar and click Create Group on the API Groups page. In the Create Group dialog box, select the instance to which the API group to be created belongs and enter the group name. In this example, set Instances to Shared Instance(VPC Network)(api-shared-vpc-002) and Group Name to testVpcGroup.

Create a group

Step 2: View details of the API group.

After you create the API group, the API group appears on the API Groups page. You can click the group name to go to the Group Details page. On this page, you can bind a domain name, modify basic information, and change the instance type.

API Gateway automatically assigns a public second-level domain name for the API group. This domain name is used only for debugging and has a limit of 100 calls per day for regions outside the Chinese mainland and 1,000 calls per day for regions in the Chinese mainland. We recommend that you bind an independent domain name after you create an API group. In this example, the default second-level domain name is used.

4. Create an API operation

In the left-side navigation pane, choose Open API > APIs. Make sure that the current region is the region where the API group you created resides. On the APIs page, click Create API.

Step 1: Configure basic information for the API.

In this step, configure basic information for the API to be created, including the API group to which the API operation belongs, the name, authentication method, type, and description of the API operation. In this example, set Group to testVpcGroup, AppCode Certification to Enable AppCode Authentication (Header & Query). Set other parameters as required and click Next.

Define an API operation

Step 2: Configure request information for the API operation.

In this step, define how a client, such as a browser, a mobile app, or a business system, calls the API operation. The parameters that you need to specify in this step include Request Type, Protocol, Request Path, HTTP Method, Request Mode, and the parameters in the Request Parameters section. Then, click Next. In this example, set Request Mode to Request Parameter Passthrough, which indicates that API Gateway passes API requests to the backend service in the VPC without processing them.

Define API Request

Step 3: Configure backend service information for the API operation.

In this step, configure the type and URL of the backend service to which API Gateway sends the requests received from a client and how parameters are mapped and processed. In this example, specify VPC for Backend Service Type, enter the VPC access authorization name you created in the "Authorize API Gateway to access the VPC" section in VPC Access Name, specify Backend Request Path, and then click Next.

Define API Backend Service

Step 4: Configure response information for the API operation.

In this step, configure response information to generate API documentation. The documentation helps API callers better understand APIs. You can set parameters such as Response ContentType, Response Example, and Error Response Example. This example does not include this step. Click Create.

Step 5: Publish the API operation.

After you click Create, a message appears to inform you that the API operation is created, as shown in the following figure. All configurations of the API operation take effect only after you publish the API operation. API Gateway provides three environments to which you can publish an API operation: Release, Pre, and Test. In this example, click Publish in the message. In the dialog box that appears, publish the API operation to Release as prompted.

Publish

5. Create and authorize an app

An app is an identity that you use to call the API operation. In Step 1 of the "Create an API operation" section, the Security Certification parameter is set to Alibaba Cloud App. Therefore, after you publish the API operation, you must create and authorize an app to call the API operation.

Step 1: Create an app.

In the left-side navigation pane, choose Call API > Apps. On the Apps page, click Create App. In the Create App dialog box, enter an App name and click Confirm. In the app list, click the name of the created APP. Two authentication modes are provided: an AppKey and AppSecret pair and AppCode. In this example, the AppCode mode is used to authenticate the app. For more information, see Call an API operation by using an AppCode.

Create an app.

Step 2: Authorize the app.

In the left-side navigation pane, choose Open API > APIs. On the APIs page, find the API operation you created and click Authorize in the Actions column. A dialog box appears, as shown in the following figure. Set the Environment parameter to the environment to which you have published the API operation. In this example, set this parameter to Release. Enter the name of the app you created in the search bar of the Choose Apps for Authorization section. In the search result, select the created app, click Add in the Actions column, and then click Confirm. A message appears to inform you that the app is authorized to call the API operation.

Grant the app the permissions to call the API operation

6. Allow outbound IP addresses of API Gateway in a security group

If the security group of your ECS instance does not allow all CIDR blocks over a specified port, you must add the outbound IP addresses of API Gateway to the security group to allow these IP addresses.

The outbound IP address of an API group is the outbound IP address of the instance to which the API group belongs. To obtain the outbound IP address of a dedicated instance, log on to the API Gateway console. In the left-side navigation pane, choose Open API > API Groups. On the API Groups page, find the API group that you want to manage, and click the group name. On the Group Details page, view information about the instance to which the API group belongs.

Dedicated instance

In the left-side navigation pane, click Instances. On the Instances page, view the information of the instance to which the API group belongs, as shown in the following figure. You can directly view the outbound IP address of a shared instance on the Instances page.

Outbound IP address

7. Debug the API operation

API Gateway supports online debugging. We recommend that you use this feature to check whether an API operation is correctly configured before you call this API operation on clients.

On the APIs page, click the name of the created API operation. On the API details page, click Debug API in the left-side navigation pane. The following figure shows the page that appears. If you have defined request parameters for the API operation, you can enter different values for the request parameters to check whether the API operation is correctly configured.

When you debug the API operation, make sure that the App Name parameter is set to the authorized app. The environment for debugging must be the one in which the app is authorized to call the API operation. Otherwise, debugging may fail. In this example, RELEASE is selected as the environment for debugging.

Debugging

8. Call the API operation

In this example, curl is used to call the API operation. For more information, see Call an API operation by using an AppCode.

Call an API operation

Note: The API operation in the production environment is called by default.

For information about the environments, see Configure different environments for an API operation.

The main purpose of this topic is to help you quickly get started. The high availability of a backend service is not considered. If you have any questions, see Use a resource in a VPC as the backend service of an API operation.