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

How backend services work

A backend service abstracts the actual backend endpoint from the API definition. Instead of hardcoding a URL in each API, you attach APIs to a backend service. API Gateway routes incoming requests to the URL configured for that backend service in the target environment.

This centralized configuration provides two key operations:

• Bulk URL updates: Change the backend URL for an environment once — all APIs using that backend service are automatically updated without requiring you to republish the APIs.

• Bulk unpublishing: Delete the backend URL for an environment — all APIs using that backend service in that environment are unpublished simultaneously.

Workflow

1. Create a backend service

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

3. Create an API

4. Create an app and authorize it to call the API

5. Debug the API

6. Manage all 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.

2. In the upper-right corner, click Create Backend Service. Select a backend service type. This example uses HTTP/HTTPS.

   Note the following when selecting a type:

   • The type cannot be changed after the backend service is created. You can update the name and description at any time.

   • Supported types: HTTP/HTTPS Service, VPC, Function Compute, OSS, EventBridge, Service discovery, Mixed, and MOCK.

Step 2: Define URLs for the backend service in each environment

1. On the Backend Services page, find the backend service you created and click Configure Backend Service and View Associated APIs in the Actions column.

   The Backend Service Definition page has four tabs: Draft, Test, Pre, and Production.

   • Draft: Lists all APIs associated with this backend service, regardless of environment.

   • Test / Pre / Production: Define a URL for the backend service in that environment, and view all APIs published to that environment using this backend service.

2. Select a tab for the target environment and click Create in the upper-right corner. This example uses the Test environment.

3. Define the URL for the selected environment, then click Publish. After publishing succeeds, proceed to create an API.

4. URL configuration varies by backend service type:

   Note

   • HTTP/HTTPS: Enter the URL of the backend service.

   • VPC: Select an authorization rule that grants API Gateway access to the virtual private cloud (VPC). Optionally select Use HTTPS to enforce HTTPS when calling the backend service.

   • Function Compute: Set Function Type to either Event Function or HTTP Function. For Event Function, configure the required parameters. For HTTP Function, specify a trigger path.

   • OSS: Grant API Gateway access to your OSS bucket before defining the URL. To grant read access, allow API Gateway to call the oss:GetObject operation. To grant write access, allow it to call oss:PutObject and oss:DeleteObject. To revoke access, 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. Click Create API in the upper-right corner.

2. In the Basic Information step, set the API group, name, authentication method, type, and description. This example selects AppCode Authentication (Header & Query) for the AppCode Authentication parameter. Click Next.

3. In the Define API request step, configure how clients call the API. Set the Request Type, Protocol, Request Path, HTTP Method, and Request Mode parameters, then add any required parameters in the Request Parameters section. This example sets HTTP Method to GET and Request Mode to Pass-through. Pass-through forwards received parameters to the backend service without parameter mapping. Click Next.

4. In the Define backend service step, configure how API Gateway routes requests to the backend. Set Configuration Mode to Use Existing Backend Service and Backend Service Type to HTTP/HTTPS Service. Select the backend service testHttp from the Backend Service drop-down list. To preview URLs configured for each environment, hover over View Environment Configurations and select the corresponding tab. After selecting the backend service, set the Backend Request Path, HTTP Method, and Backend Service Timeout Period parameters.

5. In the Define response step, configure response information for API documentation. Set the Response ContentType, Response Example, and Error Response Example parameters as needed. This step is optional — click Create to skip it.

6. After clicking Create, publish the API to an environment. API Gateway supports three environments: Production, Pre, and Test. API configurations take effect only after publishing.

   Important

   Before publishing an API that uses a backend service, make sure the backend service has a URL defined for that environment. If not, the API cannot be published.

Step 4: Create an app and authorize it to call the API

1. An app is the identity used to call an API. Because this API uses Alibaba Cloud App as the security authentication method, create an app and grant it permission to call the API after publishing.

2. In the left-side navigation pane, choose Call APIs > Apps. Alibaba Cloud App authentication supports two modes: AppKey and AppSecret, and AppCode. This example uses the AppCode mode. For details, see Call an API in simple authentication mode.

3. In the API list, find the API you created and click Authorize in the Actions column. Set Stage to the environment where the API is published. Search for and select the app you created, click Add, then click Confirm. A confirmation message appears when the app is authorized.

Step 5: Debug the API

Use the online debugging tool to verify the API before calling it from a client.

On the APIs page, click the API name, then click Debug API in the Actions column. On the API details page, select Debug API in the left-side navigation tree. If the API has request parameters defined, enter different values to verify the configuration. Set App Name to the authorized app, and make sure the debug environment matches the environment where the app is authorized. A mismatch may cause debugging to fail.

Step 6: Manage published APIs using the backend service

1. When you modify a backend service definition for an environment, all published APIs using that backend service in the environment are automatically republished with the new configuration.

2. In this example, the URL for testHttp is updated in the test environment. A confirmation message notes that modifying the backend service will be synchronized to all associated APIs. After republishing, the updated API publishing status appears in the list. All requests to APIs using this backend service in the test environment are routed to the new URL.

3. To remove a backend service from an environment, delete its URL configuration for that environment. All published APIs using the backend service in that environment are unpublished simultaneously.

   Warning

   These operations apply to all associated APIs and cannot be undone. Proceed with caution.