All Products
Search
Document Center

API Gateway:Create an API with a backend service of the HTTP type

Last Updated:Feb 29, 2024

This topic describes how to create and publish an API whose backend service is of the HTTP type in API Gateway. This topic also describes how to call the API by using an application and an AppKey and AppSecret pair based on the Alibaba Cloud App authentication type.

1. Overview

You must perform the following steps in sequence:

  • Create an API group

  • Create an API

  • Create an application and grant the application the permissions to call the API

  • Debug the API

  • Call the API

2. Create an API group

APIs are managed in API groups. You must create an API group before you create an API.

Step 1: Create an API group.

Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > 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 on which you want to create the API group, enter the group name and base path, and then click Confirm.

Step 2: View the details of the API group.

On the API Groups page, view the created group. Click the name of the group to go to the details page. On the Group Details page, you can bind a domain name, modify basic information, and change the instance type for the API group.

API Gateway automatically assigns a public second-level domain name to the API group. The domain name is used only to debug and test APIs. The number of API calls that you can initiate to access the domain name is limited to 100 calls per day in the China (Hong Kong) region and other regions outside the Chinese mainland and 1,000 calls per day in regions inside the Chinese mainland. We recommend that you bind an independent domain name after you create an API group.

3. Create an API

In the left-side navigation pane, choose Manage APIs > APIs. Select the region where the created API group resides, and then click Create API.

Step 3: Configure basic information for the API.

In this step, configure basic information for the API that you want to create, including the API group to which the API belongs and the name, authentication method, type, and description of the API. Select the group that you created from the Group drop-down list, set the Security Authentication parameter to Alibaba Cloud App and the AppCode Authentication parameter to Enable AppCode Authentication (Header & Query), configure other parameters based on your business requirements, and then click Next.

image

Step 4: Configure request information for the API.

In this step, 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 in this step include Protocol, Request Path, HTTP Method, Request Mode, and the parameters in the Request Parameters section. Then, click Next. In this example, the Request Mode parameter is set to Pass-through. This indicates that API Gateway does not process the parameters sent by the client and directly passes them to the backend.

Step 5: Configure backend service information for the API.

In this step, configure the type and URL of the backend service to which API Gateway sends the requests that are received from a client and how parameters are mapped and processed. In this example, the Backend Service Type parameter is set to HTTP/HTTPS Service. A backend service of this type can be accessed on any address that API Gateway can access on Alibaba Cloud networks and over 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.

Step 6: Configure response information for the API.

In this step, configure 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 step is skipped in this example. Click Create.

Step 7: Publish the API.

After you click Create, the following message appears to inform you that the API is created. In this example, click Publish in the message. In the dialog box that appears, set the Stage parameter to Production to publish the API as prompted.

Note

After you modify an API, you must publish the API to the corresponding environment for the modification to take effect. API Gateway provides three built-in environments, which are test, pre-release, and production.

4. Create and authorize an app

An app is an identity that you use to call the API. In Step 3 in this example, the authentication method is set to Alibaba Cloud App. Therefore, after the API is published, you must create an application and grant the application the permissions to call the API.

Step 8: Create an application.

In the left-side navigation pane, choose Call APIs > Apps. On the Apps page, click Create App. In the Create App dialog box, configure the App Name parameter and click Confirm. In the application list, click the name of the created application. The following authentication methods are provided: an AppKey and AppSecret pair and an AppCode. Each application has an AppKey and AppSecret pair. This pair works in a way similar to an account and password pair. When you call an API, you must specify the AppKey as an input parameter. The AppSecret is used to calculate the signature string. API Gateway verifies the key pair to authenticate the caller.image.png

Step 9: Authorize the application.

In the left-side navigation pane, choose Manage APIs > APIs. On the APIs page, find the created API and click Authorize in the Actions column. The following dialog box appears. Set the Stage parameter to the environment to which you published the API. In this example, the Environment parameter is set to Production. 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 app, 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.image.png

5. 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.

Step 10: Debug the API.

In the left-side navigation pane, choose Call APIs > Debug. Find the newly created API. If you defined request parameters for the API, you can enter different values for the request parameters to check whether the API is correctly configured. When you debug an API, make sure that the App Name parameter is set to the authorized application. The environment for debugging must be the one in which the application is authorized to call the API. Otherwise, the debugging may fail.

6. Call the API

By performing the preceding steps, you created and published the API, created and authorized an application to call the API, and debugged the API. In this step, SDKs provided by API Gateway can be used to call a published API from a business system.

Step 11: Call the API.

1. In the left-side navigation pane, choose Call APIs > SDK. Then, download an SDK on the API Groups or Authorized APIs tab. For more information, see Use SDKs to call APIs.

In this example, the SDK for Node.js is used to call the API.

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

Use the AppKey and AppSecret of the application that is created in this example to replace YOUR_APP_KEY and YOUR_APP_SECRET in the following code snippet.

// Import the SDK for Node.js that you downloaded.
const Client = require('aliyun-api-gateway').Client;
// Create an instance for 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 that you want to call belongs. You can use the public second-level domain name provided by API Gateway to test API calls. However, a limit is imposed on the number of API calls. We recommend that you bind an independent domain name to the API Group.
  var url = 'YOUR_GROUP_DOMAIN';
  var result = await client.get(url, {
// Specify the request header. Some APIs can return data formats based on the specified response type. We recommend that you manually define the request header based on your business requirements. 
    headers: {
      accept: 'application/json'
    },
  });
  console.log(JSON.stringify(result));
}
get().catch((err) => {
  console.log(err.stack);
});                

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

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