API Gateway:Use a backend service to create and manage APIs

Overview

To help you efficiently manage a growing number of APIs, API Gateway abstracts backend services as resources in regions. In the API Gateway console, you can create a backend service and define different URLs for the backend service for different environments. Then, you can select the backend service when you create an API that uses the backend service. This way, requests to call the API are routed to the corresponding URL of the backend service based on the environment to which the API is published. You can also manage all the published APIs that use the same backend service in a centralized manner on the page for configuring the backend service. The following scenarios, for example, are supported:

Scenario 1: After you change the URL of a backend service in the test environment, all the published APIs that use the backend service in the test environment are automatically updated without requiring you to republish the APIs. Requests to call the APIs are then routed to the new URL of the backend service in the test environment.

Scenario 2: After you delete the URL that is no longer needed for a backend service in the test environment, all the published APIs that use the backend service in the test environment are unpublished.

For more information, see the following sections.

Steps

1. Create a backend service

2. Define different URLs for the backend service in different environments

3. Create an API

4. Create an application and grant the application the permissions to call the API

5. Debug the API

6. Manage all the published APIs that use the backend service in a specific environment

Create a backend service

1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > Backend Services. The Backend Services page appears.

2. In the upper-right corner of the page, click Create Backend Service to create a backend service. In this example, the Type parameter is set to HTTP/HTTPS. You cannot create a backend service of the HTTP/HTTPS or OSS type in the China (Hong Kong) region and other regions outside the Chinese mainland.

You must select a type for each backend service that you want to create. You cannot change the type after a backend service is created, but you can change the name of the backend service. The following types are supported: HTTP/HTTPS Service, VPC, Function Compute, OSS, EventBridge, Service discovery, Mixed, and MOCK.

Define different URLs for the backend service for different environments

1. After you create a backend service, go to the Backend Services page, find the created backend service, and click Configure Backend Service and View Associated APIs in the Actions column. On the page that appears, click the Draft tab to view the APIs that use the backend service. On the Test, Pre, and Production tabs, you can define a URL for the backend service in the corresponding environment. You can also view published APIs that use the backend service in these environments on the corresponding tab.

2. Select a tab based on your business requirements, and then click Create in the upper-right corner. In this example, Test is selected.

3. Define a URL for the backend service for the selected environment. Then, click Publish. When a message indicating that the service is published appears, you can proceed to create an API.

4. Take note of the following items when you define URLs:

Create and define an API

1. In the left-side navigation pane, choose Manage APIs > APIs. On the APIs page, click Create API in the upper-right corner. The Create API page appears.

2. In the Basic Information step, configure the basic information about the API to be created, including the group to which the API belongs and the name, authentication method, type, and description of the API. Select a group, configure the other parameters, and then click Next. Enable AppCode Authentication (Header & Query) is selected for the AppCode Authentication parameter in this example.

3. In the Define API Request step, define how a client, such as a browser, a mobile app, or a business system, sends a request for the API. Configure the Request Type, Protocol, Request Path, HTTP Method, and Request Mode parameters and add parameters in the Request Parameters section. Then, click Next. In this example, the HTTP Method parameter is set to GET and the Request Mode parameter is set to Pass-through. A value of Pass-through specifies that API Gateway passes the received parameters to the backend service without processing. Then, click Next.

4. In the Define Backend Service step, define how API Gateway processes a received request, specifically, how API Gateway maps parameters and to which backend service URL it sends the processed request. In this example, testHttp is selected. Move the pointer over the service to view its URL in different environments. After you select the backend service, configure other settings based on the backend service type. For an API that uses an HTTP backend service, you must configure the request path, HTTP method, and backend timeout period. Then, click Next.

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

6. After you click Create, a message appears to inform you to publish the API. API Gateway provides three environments to which you can publish an API: Production, Pre, and Test. All configurations that you perform on an API can take effect only after you publish the API to a required environment.

   Important

   Before you publish an API that uses a backend service to an environment, make sure that the backend service is defined in the environment. Otherwise, you cannot publish the API.

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

1. An application is an identity that you use to call an API. In the preceding step for creating the API, the Security Authentication parameter is set to Alibaba Cloud App. After you publish the API, you must create an application and grant the application the permissions to call the API.

2. 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. Two authentication modes are provided for the Alibaba Cloud App security authentication method: an AppKey and AppSecret pair and an AppCode. In this example, the AppCode mode is used to authenticate the app. For more information, see Call an API in simple authentication mode.

3. In the API list, find the created API and click Authorize in the Actions column. Set the Stage parameter to the environment to which you published the API. Enter the name of the application you created in the search box to the right of the Choose Apps for Authorization parameter. In the search result, select the application that you created, 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.

Debug the API

Debug the API after the authorization is successful. API Gateway supports online debugging. We recommend that you use this feature to check whether an API is correctly configured before you call the API on a client. On the APIs page, click the name of the created API. that you created and click Debug API in the Actions column. On the API details page, click Debug API in the left-side navigation tree. If you have 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 the 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.

Manage APIs

1. When you modify the definition of a backend service in an environment, all published APIs that use the backend service in the environment are batch republished and refreshed.

2. In this example, the URL is modified for testHttp in the test environment. A message that indicates the environment has published APIs and the modification will be synchronized to all the APIs appears. After the backend service is republished, the API publishing result is displayed in the list. When you call an API that uses the backend service in the test environment, the request is forwarded to the new URL.

3. If the URL of a backend service is no longer required in an environment, you can delete the backend service from the environment. The published APIs that use the backend service in the same environment are deleted in a synchronous manner.

   Warning

   The preceding operations are performed on all associated APIs and are irreversible. Proceed with caution.