All Products
Search
Document Center

Use a backend service to create and manage APIs

Last Updated: Mar 07, 2022

This topic describes how to create a backend service in the API Gateway console. This topic also describes how to use the created backend service to create, publish, 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 in 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 a backend service in a centralized manner on the page for configuring the backend service. For example, the following scenarios 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 text.

Procedure

  1. Create a backend service.

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

  3. Create and define an API.

  4. Create an app and grant the app 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 Open API > Backend Services. The Backend Services page appears.Backend Services page

  2. Click Create Backend Service in the upper-right corner of the page. In the Create Backend Service dialog box, create a backend service. In this example, the Type parameter is set to HTTP/HTTPS Service.Create Backend Service dialog box

You must specify a type for each backend service, as shown in the preceding figure. After a backend service is created, you cannot change its type. However, you can change the name and description of the backend service as required. The valid values of the Type parameter are HTTP/HTTPS Service, VPC, Function Compute, OSS, and MOCK.

Notice

API Gateway of the current version does not support Object Storage Service (OSS) as the backend service on Finance Cloud or Alibaba Gov Cloud. API Gateway of future versions will allow you to create APIs that use OSS as the backend service on Finance Cloud and Alibaba Gov Cloud.

Define different URLs for the backend service in different environments

  1. Find the backend service that you created and click Configure Backend Service and View Associated APIs in the Actions column. The Backend Service Definition page appears.The page contains four tabs, as shown in the preceding figure. On the Draft tab, you can view all the APIs that use the backend service. On each of the Test, Pre, and Production tabs, you can define a URL for the backend service and view all the published APIs that use the backend service.Backend Service Definition page

  2. Click one of the Test, Pre, and Production tabs. In this example, click the Test tab. Click Create in the upper-right corner.On the Define Backend Service page, enter a URL for the backend service and click Publish, as shown in the preceding figure. The Published message appears. Then, you can create an API.Define a backend service URL

  3. Take note of the following description when you define URLs for different types of backend services.

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, allow API Gateway to perform the oss:GetObject operation on the OSS bucket. To grant the write permissions to API Gateway, allow API Gateway to perform 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.

Create and define an API

  1. In the left-side navigation pane, choose Open API > 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. To facilitate subsequent testing, set the AppCode Authentication parameter to Enable AppCode Authentication (Header & Query).Basic Information step

  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 processing. Define API Request step

  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 testHttp backend service that you create 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.Define Backend Service step

  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.

    Notice

    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 app and grant the app the permissions to call the API

  1. An app is an identity that you use to call the 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 app and grant the app the permissions to call the API.

  2. In the left-side navigation pane, choose Call API > Apps. On the Apps page, click Create App in the upper-right corner. In the Create App dialog box, enter an app name and click Confirm. In the app list, click the name of the created app. The App Details page appears, as shown in the following figure. Two authentication modes are provided for the security authentication method Alibaba Cloud App: an AppKey and AppSecret pair and AppCode. In this example, the AppCode mode is used to authenticate the app. For more information about the security authentication method Alibaba Cloud App, see Call an API operation by using an AppCode.App Details page

  3. 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. The Authorize dialog box appears, as shown in the following figure. Set the Stage parameter to the environment to which you publish the API. Enter the name of the app that 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 app is authorized to call the API.Grant the app the permissions 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. 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, 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 app. The environment for debugging must be the one in which the app is authorized to call the API. Otherwise, the debugging may fail.

  1. Debugging

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

  1. If you modify the definition of the backend service in a specific environment, all the published APIs that use the backend service in the environment are automatically updated. The following figure shows an example.Multiple APIs that use the testHttp backend service are published to the test environment, as shown in the preceding figure. Click Modify in the upper-right corner of the Basic Information section. On the Define Backend Service page, change the backend service URL and click Publish. A message appears to inform you that the backend service URL will be updated for all the published APIs that use the backend service in the test environment.Test tabMessage

    After you confirm to modify the definition of the backend service, you can see that the published APIs in the API list are updated. When you send requests to call the APIs again, the requests are routed to the new backend service URL.Publishing results

  2. If the backend service URL that you define for a specific environment is no longer needed, you can delete the definition of the backend service in the environment.If you delete the definition of the backend service in the environment, all the published APIs that use the backend service in the environment are unpublished. The following figure shows an example.DeleteUnpublish multiple APIs at a time

    Warning

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