All Products
Search
Document Center

API Gateway:Create an API with HTTP as the backend service type

Last Updated:Dec 07, 2022

This topic describes how to create and publish an API with HTTP as the backend service type in API Gateway. This topic also describes how to call the API by using the AppKey and AppSecret pair of an app, with Security Certification set to Alibaba Cloud APP.

1. Overview

You must perform the following steps in sequence:

  • Create an API group

  • Create an API operation

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

  • Debug the API operation

  • Call the API operation

2. Create an API group

APIs are managed in API groups. Before you create an API, 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 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) and enter testAppkeyGroup in the Group Name field.

image

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 to the API group. This domain name is for debugging and testing purposes only. If you use this domain name to make API calls, you can make 100 calls per day in regions outside the Chinese mainland and 1,000 calls per day in 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.

3. 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 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, type, and description of the API operation. In this example, set Group to testAppkeyGroup, Security Certification to Alibaba Cloud App, and AppCode Certification to Disable AppCode Authentication, configure other parameters as required, and then click Next.

image

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 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, enter /web/cloudapi in the Request Path field and do not define request parameters.

image

Step 5: 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, set the Backend Service Type parameter to HTTP/HTTPS 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. Configure other parameters such as Backend Request Path as prompted and click Next.

image

Step 6: Configure response information for the API operation

In this step, configure response information to generate API documentation. The documentation helps API callers better understand the API operation. You can set parameters such as Response ContentType, Response Example, and Error Response Example. In this example, this step is skipped. Click Create.

Step 7: 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. API Gateway provides three environments to which you can publish an API operation: Production, Pre, and Test. All configurations you perform on an API operation can take effect only after you publish the API operation to a required environment. In this example, click Publish in the message that indicates successful API creation. In the Publish API dialog box, set the Stage parameter to Production, enter remarks, and then click Publish.

image

4. Create and authorize an application

An app is an identity that you use to call the API operation. In Step 3, the Security Authentication parameter is set to Alibaba Cloud App. Therefore, after you publish the API operation, you must create an app and grant the app the permissions to call the API operation.

Step 8: 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. Each app has an AppKey and AppSecret pair. This pair works in a way similar to an account and password pair. When you call an API operation, you must pass in the AppKey as an input parameter. AppSecret is used to calculate the signature string. API Gateway authenticates the key pair to verify your identity. For more information about this mode, see Call an API operation by using an AppCode.

image

Step 9: Authorize the application

In the left-side navigation pane, choose Open API > APIs. On the APIs page, find the created API and choose More > Authorize in the Actions column. A dialog box appears, as shown in the following figure. Set the Stage parameter to the environment to which you have published the API operation. In this example, the Stage parameter is set to Production. Search for the app you created, click Add, and then click OK. A message appears to inform you that the app is authorized to call the API operation.

image

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 call this API operation on clients.

Step 10: Debug the API operation

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, the debugging may fail. In this example, Production is selected as the environment for debugging.

image

6. Call the API operation

After you debug and publish an API operation to a Production environment and create and authorize an app to call the API operation, you can use SDKs for API Gateway to call the API operation in your business system.

Step 11: Call the API operation

In the left-side navigation pane, choose Call API > Authorized API SDK. You can download the SDK that is used to call the API operation by using your app. You can also download the SDK for other coding languages.

image

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 app 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 app. Specify the AppKey and AppSecret of the authorized app.
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 the result.1

3. Use curl to call the API operation. Find the authorized app on the Apps page, click the app, and obtain its AppCode on the page that appears. Then call the API operation in the similar way that is shown in the following example.

curl -i --get --include 'http:///' -H 'Authorization:APPCODE the AppCode that you obtained'

The following figure shows the result of an API call.

Call an API operation by using curl