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 authorize it to call the API

5. Debug the API

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

Step 1: 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 and description of the backend service.

   • The following types are supported: HTTP/HTTPS Service, VPC, Function Compute, OSS, EventBridge, Service discovery, Mixed, and MOCK.

Step 2: Define different URLs for the backend service in different environments

1. Find the created backend service on the Backend Services page and click Configure Backend Service and View Associated APIs in the Actions column. The Backend Service Definition page appears. The page provides four tabs, namely Draft, Test, Pre, and Production. You can view all APIs that use the backend service on the Draft tab. You can define a URL for the backend service in the respective environment on the Test, Pre, and Production tabs. You can also view the published APIs that use the backend service in an environment 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:

   Note

   • If you use an HTTP or HTTPS backend service, you need only to enter the URL of the backend service.

   • If you use a resource in a virtual private cloud (VPC) as the backend service, you must select an authorization rule that you create when you authorize API Gateway to access the VPC. Select Use HTTPS as required. If you select Use HTTPS, the HTTPS protocol is used to request the backend service.

   • If you use Function Compute as the backend service, you must specify whether to select Event Function or HTTP Function for the Function Type parameter. If you select Event Function, configure the parameters as required. If you select HTTP Function, specify a trigger path.

   • If you use OSS as the backend service, you must authorize API Gateway to access objects in your OSS bucket. To grant the read permissions to API Gateway, you must allow API Gateway to call the oss:GetObject operation on the OSS bucket. To grant the write permissions to API Gateway, you must allow API Gateway to call the oss:PutObject and oss:DeleteObject operations on the OSS bucket. To revoke the permissions granted to API Gateway, you can manually delete the relevant authorization policies from the OSS bucket.

Step 3: Create 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, set the HTTP Method parameter to GET and the Request Mode parameter to Pass-through. A value of Pass-through indicates that API Gateway passes the received parameters to the backend service without mapping the parameters.

4. In the Define Backend Service 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. The following example describes how to use an existing backend service. Select Use Existing Backend Service for the Configuration Mode parameter and HTTP/HTTPS Service for the Backend Service Type parameter. The console automatically searches for backend services of the selected type. Select the backend service testHttp that you created from the Backend Service drop-down list. To view the URLs of the backend service in different environments, move the pointer over View Environment Configurations and click the corresponding tabs. After you select a backend service, configure the other parameters that appear based on the type of the backend service. To create an API that uses an HTTP or HTTPS backend service, you must set the Backend Request Path, HTTP Method, and Backend Service Timeout Period parameters.

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.

Step 4: Create an application and authorize it 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 app the permissions to call the API.

2. In the left-side navigation pane, choose Call APIs > Apps. 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 about this mode, 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 publish 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.

Step 5: 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, 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.

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

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 indicating that the environment has published APIs and that 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.