This topic describes how to create and publish an API with a resource in a virtual private cloud (VPC) as the backend service in API Gateway, and how to call the API by using an application and an AppCode. The AppCode is automatically generated for the application when you set the authentication method of the API to Alibaba Cloud App.
Prerequisites
A VPC environment is created. For more information, see Create a VPC with an IPv4 CIDR block and Create a VPC with an IPv6 CIDR block.
An Elastic Compute Service (ECS) instance is created. For more information, see Step 1: Create an ECS instance.
Server Load Balancer (SLB) and ECS instances must be created, and a service must be up and running in the VPC.
In this example, an ECS instance is created in a VPC. On the ECS instance, a web service is deployed by using nginx and port 80.
Process
The following items describe the overall process for configuring API Gateway access to a backend service in a VPC based on an API:
Create a VPC access authorization
To allow API Gateway to access your VPC, you must first create a VPC access authorization.
Log on to the API Gateway console. In the top navigation bar, select a region. In the left-side navigation pane, choose Manage APIs > VPCs.
On the VPC Access Authorizations page, click Create Authorization in the upper-right corner.
In the Create VPC Access dialog box, specify the VPC Access Name, VPC Id, Instance ID or IP Address, and Port Number parameters.
NoteYou can specify a domain name in the Host field to access a vhost on an SLB instance or ECS instance.
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 ECS instance details.
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.
Creates an API group
APIs are managed in API groups. You must create an API group before you create an API.
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups. On the API Groups page, click Create Group in the upper-right corner.
In the Create Group dialog box, select an instance from the Instances drop-down list, set Group Name to
nginx-demo, set BasePath to/, and then click Confirm. You can set other values for these parameters based on your business requirements. This topic provides only examples.
On the API Groups page, view the created group and click the group name to go to the Group Details page. You can perform operations such as Bind Domain Name, Modify Basic Information, and Modify Instance for API Group Deployment.
API Gateway automatically assigns a public second-level domain name to the API group. This domain name is used only for debugging and has a limit of 100 calls per day for the China (Hong Kong) region and other 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.
Create an API
Log on to the API Gateway console. In the top navigation bar, select a region. In the left-side navigation pane, choose Manage APIs > API Groups.
On the API Groups page, find the
nginx-demogroup that you created and click Manage APIs in the Actions column.On the APIs page, click Create API in the upper-right corner.
In the Basic Information step of the Create API wizard, configure the following parameters and click Next.
Parameter
Example
Group
nginx-demo
API Name
nginx-test
Security Authentication
Alibaba Cloud App
AppCode Authentication
Enable AppCode Authentication (Header & Query)
Signature Algorithm
HMAC_SHA256
In the Define API Request step, configure the following parameters and click Next.
Parameter
Example
Protocol
HTTP and HTTPS
Request Path
/nginx
HTTP Method
GET
Request Mode
Pass-through
NoteIn this step, you define how a client, such as a web browser, a mobile app, or a business system, requests the API. The parameters that you need to configure include Protocol, Request Path, HTTP Method, Request Mode, and the parameters in the Request Parameters section. In this example, Request Mode is set to Pass-through, which indicates that API Gateway directly passes API requests to the backend service in the VPC without processing them.
In the Define Backend Service step, configure the following parameters and click Next.
Parameter
Example
Configuration Mode
Customize Backend Service
Backend Service Type
VPC
VPC Access Name
***-microservice
Backend Request Path
/
HTTP Method
GET
Backend Service Timeout Period
10000
NoteIn this step, you configure the type and URL of the backend service to which API Gateway sends the requests received from a client and how request parameters are mapped and processed. In this example, VPC is specified for Backend Service Type, the VPC access authorization you created earlier is specified for VPC Access Name, and a path is specified for Backend Request Path.
In the Define Response step, configure the parameters on the page based on your business requirements and then click Create.
NoteIn this step, you specify the response information to generate API documentation. The documentation helps API callers better understand the API. You can set parameters such as Response ContentType, Response Example, and Error Response Example. This example does not include this step. Click Create.
In the message that appears, click Publish.
In the Publish API dialog box that appears, set Environment to Release, enter remarks in the Remarks section, and then click Publish.
NoteIf you modify an API, the modification takes effect only after you publish the API to the corresponding environment. API Gateway provides three environments to which you can publish an API: Release, Pre, and Test.
Create an application and authorize the application to call the API
An application is an identity that you use to call an API. In the Create an API step, the authentication type is set to Alibaba Cloud App. Therefore, after you publish the API, you must create and authorize an application to call the API.
Create an application
Log on to the API Gateway console. In the top navigation bar, select a region. In the left-side navigation pane, choose Call APIs > Apps.
On the Apps page, click Create App in the upper-right corner.
In the Create App dialog box, configure the App Name parameter and click Confirm.
On the Apps page, click the name of the application that you created to go to the App Details page. Two authentication modes are provided for the security authentication method Alibaba Cloud App: an AppKey and AppSecret pair and an AppCode. In this example, an AppCode is used. For more information, see Call an API in simple authentication mode.
Authorize the application to call the API
Log on to the API Gateway console. In the top navigation bar, select a region. In the left-side navigation pane, choose Manage APIs > APIs.
On the APIs page, find the created
nginx-testAPI and choose
> Authorize in the Actions column. On the Authorize page, set the Environment parameter to Release. Enter the name of the application you created in the search bar of the Choose Apps for Authorization section. In the search result, select the created application, click Add in the Actions column, and then click Confirm. A message appears to inform you that the application is authorized to call the API.
Allow the egress 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 egress IP addresses of API Gateway to the security group to allow these IP addresses. The egress IP addresses of API Gateway refer to the egress IP addresses of the API Gateway instance on which the API group resides.
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups. On the API Groups page, click the name of the API group that you created.
On the Group Details page, view the Instance Type parameter.
In the left-side navigation pane, choose Instances and Clusters > Shared Instances or Instances and Clusters > Dedicated Instances based on the instance type that you obtained. On the page that appears, scroll to the Outbound Addresses parameter of the instance based on the instance ID to view the egress IP addresses of the instance.
Log on to the ECS console. In the left-side navigation pane, choose Instances & Images > Instances. Click the created ECS instance to go to the details page. Click the Security Groups tab and click the security group that you want to manage. On the Security Group Details tab, click the Inbound tab and then click Quick Add. In the Quick Add dialog box, configure the egress IP addresses of API Gateway.
Debug the API
API Gateway supports online debugging. We recommend that you use this feature to check whether an API is correctly configured before you call this API on clients.
Log on to the API Gateway console. In the left-side navigation pane, choose Call APIs > Debug.
On the Debug API page, select the
nginx-testAPI that you created, set Verification Method to Use AppCode, and then click Send Request. The following information indicates that the configuration is successful.
Call the API
For more information, see Client-based API Calls.
If no environment is specified for debugging, the API is debugged in the production environment by default. For more information about API environments, see Environment Management.
The 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.