This topic describes how to create and publish an API operation with HTTP as the backend service in API Gateway, and how to call the API operation in an application by using an AppKey and an AppSecret. The AppKey and AppSecret are automatically generated for the application provided that you set the authentication method of the API operation to Alibaba Cloud APP.

1. Overview

You must perform the following steps in sequence:

  • Create an API group
  • Create an API operation
  • Create and authorize an application
  • Debug the API operation
  • Call the API operation

2. Create an API group

In API Gateway, 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 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 an instance to which the API group to be created belongs and enter a group name. In this example, set the Instance parameter to Shared Instance(VPC Network)(api-shared-vpc-001) and enter testAppkeyGroup in the Group Name field.

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 details page, where you can perform operations such as binding a domain name, modifying basic information, and changing 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 only be used for testing 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 for testing API calls is used.

3. Create an API operation

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

Step 3: 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, and description of the API operation. In this example, set the Group parameter to testAppkeyGroup, the Security Certification parameter to Alibaba Cloud APP, and the AppCode Certification parameter to Disable AppCode authentication. Set other parameters as required and click Next.

Step 4: 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 set in this step include Request Type, Protocol, Request Path, HTTP Method, Request Mode, and those in the Input Parameter Definition section. In this example, enter /web/cloudapi in the Request Path field and do not define request parameters.

Step 5: 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 relationship between request and response parameters. In this example, set the Backend Service Type parameter to HTTP(s) Service. The backend service address must be accessible on Alibaba Cloud networks and the Internet. For information about other backend service types, see API Gateway documentation. Set other parameters such as Backend Service Address and Backend Request Path as prompted.

Step 6: Configure response information for the API operation

In this step, configure response information to generate an API reference in Alibaba Cloud API Gateway SDK. This API reference can help API users better understand the API operation. You can set parameters such as ContentType of Response, Sample of Returned Results, and Sample of Returned Failure. In this example, this step is skipped. Click Create.

Step 7: Publish the API operation

After you create or modify the API operation, a message appears to inform you that the API operation is created or 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.

4. Create and authorize an application

Applications are identities that you use to call API operations. In step 3, the Security Certification parameter is set to Alibaba Cloud APP. Therefore, after you publish the API operation, you must create and authorize an application for calling the API operation.

Step 8: Create an application

In the left-side navigation pane, choose Consume APIs > APPs. On the APP List page, click Create APP. As shown in the following figure, for an API operation whose Security Certification parameter is set to Alibaba Cloud APP, two authentication modes are provided for its applications: AppKey and AppCode. The AppKey mode provides a key pair that consists of an AppKey and an AppSecret. You can regard them as an account and a password. When you call the API operation, you must specify the AppKey as a request parameter. The AppSecret is used to calculate the signature string. API Gateway authenticates the key pair to verify your identity. For more information about the Alibaba Cloud APP authentication method, see Call an API operation by using an AppCode.

Step 9: Authorize the application

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. Search for the application you created, click Add, and then click OK. A message appears to inform you that the application is authorized to call the API operation.

5. 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 it to be called on clients.

Step 10: Debug the API operation

On the API List page, find the API operation you created and click Debug in the Operation column. A page appears, as shown in the following figure. 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.

6. Call the API operation

Now you have created the API operation and the application, authorized the application to call the API operation, debugged the API operation, and published the API operation to the online environment. In this step, you can download Alibaba Cloud API Gateway SDK for the API operation and use the SDK to call the API operation in your business system.

Step 11: Call the API operation

In the left-side navigation pane, choose Consume APIs > Authorized APIs SDK. On the Authorized APIs SDK Auto-Generation page, you can download the SDK that is used to call the API operation in the application. You can also download the SDK for other coding languages.

In this example, Alibaba Cloud API Gateway SDK for Node.js is used to call the API operation.

1. Use Node Package Manager (NPM) to install Alibaba Cloud API Gateway SDK for Node.js. Run the following command in NPM: $ npm install aliyun-api-gateway -S.

2. Replace YOUR_APP_KEY and YOUR_APP_SECRET in the following code snippet with the AppKey and AppSecret of the application that is created in this example.

// Import Alibaba Cloud API Gateway SDK for Node.js that you downloaded.
const Client = require('aliyun-api-gateway').Client;
// Create an instance of the authorized application. Specify the AppKey and AppSecret of the authorized application.
const client = new Client('YOUR_APP_KEY','YOUR_APP_SECRET');
async function get() {
// Use the domain name of the API group to which the API operation to be called belongs. You can use the public second-level domain name provided by API Gateway to test API calls, but only for a limited number of times per day. We recommend that you bind an independent domain name to the API Group.
  var url = 'YOUR_GROUP_DOMAIN';
  var result = await client.get(url, {
// Define the response format in the request header of the API operation. All responses of the API operation will adhere to the defined response format. We recommend that you define the response format based on your requirements. 
    headers: {
      accept: 'application/json'
    },
  });
  console.log(JSON.stringify(result));
}

get().catch((err) => {
  console.log(err.stack);
});		

The following figure shows a sample response.