All Products
Search
Document Center

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

Last Updated: Sep 28, 2020

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 application by using an AppCode. The AppCode is automatically generated for the application 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 an API group

  • Create and define an API operation

  • Create an application and authorize 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 SLB and 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

Create VPC access authorization.

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

In the left-side navigation pane of the API Gateway console, choose Publish APIs > VPC Access. On the VPC Access List page, select the region where the VPC resides and click Create VPC Access. In the Create VPC Access dialog box, enter testVpc in the VPC Access Name field and specify VPC Id, Instance Id Or IP, and Instance Port.

Create VPC access authorization

VPC Id is the ID of the VPC where your backend service resides. Instance Id Or IP is the ID or private IP address of the instance where your backend service resides. You can obtain the information in the instance details.

vpcidInstance ID

3. Create an API group

API Gateway allows you to manage API operations based on 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 Publish APIs > API Groups. Select a region in the top navigation bar and click Create Group on the Group List 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 the Instance parameter to Shared Instance(VPC Network)(api-shared-vpc-001) and enter testVpcGroup in the Group Name field.

Create an API group

Step 2: View details of the API group.

After you create the API group, the API group appears on the Group List 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.

After an API group is created, API Gateway automatically creates a public second-level domain name for the API group. This default second-level domain name can be used only to test API calls and can be used for a maximum of 1,000 times per day. 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 Publish APIs > APIs. Make sure that the current region is the region where the API group you created resides. On the API List page, click Create API.

Step 1: Configure basic information for the API operation.

In this step, configure the basic information for the API operation to be created, including the API group to which the API operation belongs and the name, authentication method, type, and description of the API operation. In this example, set the Group parameter to the API group you created and the AppCode Certification parameter to Allow 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, sends a request for the API operation. The parameters to be configured in this step include Request Type, Protocol, Request Path, HTTP Method, Request Mode, and those in the Input Parameter Definition section. In this example, set the Request Mode parameter 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 a backend service type and address for the API operation and the mapping between request and response parameters. In this example, specify VPC for Backend Service Type, enter the VPC access name you created in the "Authorize API Gateway to access the VPC" section in the VPC Access Name field, 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 an API reference in the Alibaba Cloud API Gateway documentation. This API reference can help API users better understand the API operation. You can configure parameters such as ContentType of Response, Sample of Returned Results, and Sample of Returned Failure. Parameter configuration is not required in this example. Click Create.

Step 5: Publish the API operation.

After the preceding operation is successful, a message appears to inform you that the API operation is modified. 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 Deploy in the message. In the dialog box that appears, set the Select The Stage To Release To parameter to Release, enter your remarks, and then click Deploy.

Publish an API operation

5. Create and authorize an application

Applications are identities that you use to call API operations. In Step 1 of the "Create an API operation" section, the Security Certification parameter is set to Call an API operation by using an AppCode. Therefore, after you publish the API operation, you must create and authorize an application for calling the API operation.

Step 1: Create an application.

In the left-side navigation pane, choose Consume APIs > APPs. On the APP List page, click Create APP. In the Create APP dialog box, enter an application name and click OK. In the application list, click the name of the application you created. Two authentication modes are provided for the applications of an API operation whose Security Certification parameter is set to Alibaba Cloud APP: AppKey and AppCode, as shown in the following figure. In this example, the AppCode mode is used to authenticate the application. For more information about the security certification method Alibaba Cloud APP, see Call an API operation by using an AppCode.

Create an application

Step 2: Authorize the API operation.

In the left-side navigation pane, choose Publish APIs > APIs. On the API List page, find the API operation you created and click Authorize in the Operation column. A dialog box appears, as shown in the following figure. Set the Select The Stage For Authorization 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 application you created in the search bar of the Select The APP For Authorization section. In the search result, select the application you created, click Add in the Operation column, and then click OK. A message appears to inform you that the application is authorized to call the API operation.

Authorization

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 an exclusive instance, log on to the API Gateway console. In the left-side navigation pane, choose Publish APIs > API Groups. On the Group List page, find the API group whose information you want to view and click the group name. On the Group Details page, view information about the instance to which the API group belongs.

Exclusive

In the left-side navigation pane, click Instances. On the Instance list page, view the information of the instance to which the API group belongs, as shown in the following figure. You can view the outbound IP address of a shared instance on the Instance list 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 allow clients to call it.

On the API List page, find the API operation you created and click Debug in the Operation column. 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 AppName parameter is set to an authorized application. The Stage parameter must be set to the environment where the application is authorized. Otherwise, the debugging may fail. In this example, set the Stage parameter to RELEASE.

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 the API operation

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

For information about the environments of API operations, 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 service in a VPC as the backend service of an API operation.