All Products
Search
Document Center

Configure different environments for an API operation

Last Updated: Sep 28, 2020

1. Overview

API Gateway allows you to configure the test, staging, and production environments for an API operation, which correspond to the Test, Pre, and Release environments in the API Gateway console, respectively. This meets your need to call an API operation in different R&D scenarios. For example, you can configure the test environment for an API operation. In the test environment, the API operation uses appropriate resources in the test environment as its backend service. In this way, testers can simulate API calls in the production environment.

To configure different environments for an API operation in the API Gateway console, you must perform the following operations:

  • Configure an environment variable in the API group to which the API operation belongs. Specify different values for the environment variable in the test, staging, and production environments. Use this environment variable to configure the backend service of the API operation. In this way, API Gateway will route requests for the API operation to different backend service addresses as configured.

  • Configure that each API request from clients must specify the environment in which the API operation is to be called. API Gateway provides you with two methods. You can bind the API group, to which the API operation belongs, to different domain names for different environments. Alternatively, you can add the

    X-Ca-Stage

    parameter as a request parameter of the API operation.

This topic provides three examples of how to configure different environments for an API operation. The backend services of the three API operations are a service that is deployed in a virtual private cloud (VPC), an HTTP service, and a function that is created in the Function Compute console, respectively. In the three examples, one or both of the methods that API Gateway provides are used to ensure that each API request specifies the environment in which the API operation is to be called. The examples in this topic will help you understand the fundamental working principles. Even if your business situation is different from all the examples, you will figure out how to configure different environments for an API operation based on your business requirements.

2. Configure different environments for an API operation whose backend service is in a VPC by adding the X-Ca-Stage parameter as a request parameter of the API operation

2.1 Preparations

In this example, create two Elastic Compute Service (ECS) instances in the ECS console, as shown in the following figure. The two ECS instances must reside in two different VPCs. One of the ECS instances hosts the backend service of an API operation in the production environment. The other ECS instance hosts the backend service of the API operation in the test environment.

Make sure that TCP port 80 of each ECS instance is available. Install NGINX on each ECS instance as a web server for providing HTTP services. For each HTTP request, the two ECS instances return {"env":"test env"} and {"env":"relese env"}, respectively.

Note

This example is used only to describe how to configure different environments for an API operation in API Gateway. Therefore, factors that are important to a backend service in reality, such as high availability, scalability, and security, are not carefully considered in this example. We recommend that you take these factors into account when you deploy your own backend services.

2.2 Configure backend service information for the API operation

Step 1: In this example, the backend service of the API operation is deployed in two VPCs. Therefore, you must authorize API Gateway to access the two VPCs by creating two authorization entries in the API Gateway console: backend-vpc-release and backend-vpc-test. The two authorization entries are used to authorize API Gateway to access the backend service of the API operation in the production environment and the test environment, respectively. For more information, see Create an API operation with a resource in a VPC as the backend service. The following figure shows the two authorization entries.

Step 2: Create an API group in the API Gateway console. On the Group List page, find the API group and click View Stages in the Operation column.

Step 3: On the Stage Management page, create an environment variable on both the Release and Test tabs. In this example, create an environment variable named backend-host. Specify its value as backend-vpc-release on the Release tab and backend-vpc-test on the Test tab, as shown in the following figures.

Note

For each environment variable, keep its name consistent in different environments. If you have multiple API operations in the same API group and you need to configure an environment variable for each API operation, we recommend that you set an informative name for each environment variable for easy identification.

Step 4: Create an API operation in the current API group. In the Define API Backend Service step, enter the name of the environment variable in the VPC Access Name field. In this example, enter #backend-host#.

Note

In the API Gateway console, each environment variable must be expressed in the #Variable name# format, for example, #Service# and #Function#.

Step 5: Complete other configurations for the API operation. Then, publish the API operation to the production and test environments, as shown in the following figure.

Step 6: Authorize two applications to call the API operation. Note that when you authorize an application, you must specify the environment in which the application can call the API operation, as shown in the following figure. You can also authorize an application to call an API operation in all environments. For demonstration purposes, the API operation can be called anonymously in this example.

2.3 Add the X-Ca-Stage parameter as a request parameter of the API operation

  • To call the API operation in the production environment, you do not need to specify the X-Ca-Stage parameter in each API request, as shown in the following figure.

  • To call the API operation in the staging environment, which is inapplicable in this example, you must add the key-value pair

    X-Ca-Stage: PRE

    in each API request.

  • To call the API operation in the test environment, you must add the key-value pair

    X-Ca-Stage: TEST

    in each API request, as shown in the following figure.

3. Configure different environments for an API operation whose backend service is an HTTP service by binding the API group to different domain names for different environments

3.1 Preparations

In this example, create two ECS instances in the ECS console, as shown in the following figure. One of the two ECS instances hosts the backend HTTP service of an API operation in the production environment. The other ECS instance hosts the backend HTTP service of the API operation in the test environment. Make sure that TCP port 80 of each ECS instance is available. Install NGINX on each ECS instance as a web server for providing HTTP services. For each HTTP request, the two ECS instances return {"env":"test env"} and {"env":"relese env"}, respectively.

Note

This example is used only to describe how to configure different environments for an API operation in API Gateway. Therefore, factors that are important to a backend service in reality, such as high availability, scalability, and security, are not carefully considered in this example. We recommend that you take these factors into account when you deploy your own backend services.

3.2 Configure backend service information for the API operation

Step 1: Create an API group in the API Gateway console. On the Group List page, find the API group and click View Stages in the Operation column.

Step 2: On the Stage Management page, create an environment variable on both the Release and Test tabs. In this example, create an environment variable named backend-host. Specify its value as the public IP addresses of the two ECS instances correspondingly on the Release and Test tabs, as shown in the following figures.

Step 3: Create an API operation in the current API group. In the Define API Backend Service step, enter the name of the environment variable in the Backend Service Address field. In this example, enter http://#backend-host#.

Step 4: Complete other configurations for the API operation. Then, publish the API operation to the production and test environments.

Step 5: Bind the API group to different domain names for API calls in different environments. On the Group List page, find the API group to which the API operation belongs and click Bind Domain in the Operation column.

Step 6: Bind the API group to two domain names, one for the test environment and the other for the production environment, as shown in the following figure.

3.3 Call the API operation by using the domain names

  • To call the API operation in the production environment, use the domain name for the production environment in each API request, as shown in the following figure.

  • To call the API operation in the staging environment, which is inapplicable in this example, use the domain name for the staging environment in each API request.

  • To call the API operation in the test environment, use the domain name for the test environment in the API request, as shown in the following figure.

Note: In an API request, the domain name of the API group to which the API operation belongs takes precedence over the specified X-Ca-Stage parameter. Assume that you have bound the API group to different domain names for different environments and the X-Ca-Stage parameter is also specified in an API request. API Gateway will route the API request to an appropriate environment based on the domain name in the API request, as shown in the following figure.

4. Configure different environments for an API operation with Function Compute as the backend service by binding the API group to different domain names for different environments and also adding the X-Ca-Stage parameter as a request parameter of the API operation

4.1 Configure backend service information for the API operation

Create an API operation. In the Define API Backend Service step, configure a function that you created in the Function Compute console as the backend service of the API operation, as shown in the following figure. For more information, see Use Function Compute as the backend service of an API operation.

To configure different environments for the API operation, you can use the following methods:

  • Create an environment variable and set its value to different service names or function names. Then, enter the name of the environment variable in the

    Service Name

    or

    Function Name

    field. In this way, requests for the API operation will be handled by different services or functions in different environments.

  • In the Function Compute console, create an alias for each version of a service that you want to use as the backend service of the API operation. Service aliases are used to support the version management feature of Function Compute. You can create an alias for each version of a service. For more information, see

    Alias operations

    . In the API Gateway console, create an environment variable and set its value to the aliases of different versions of the service. Then, enter the name of the environment variable in the Function Alias field. In this way, requests for the API operation will be handled by different versions of the service.

4.2 Bind the API group to different domain names for different environments and add the X-Ca-Stage parameter as a request parameter of the API operation

Assume that you want API callers to specify the X-Ca-Stage parameter in each API request that uses an independent domain name of the API group to which the API operation belongs. When you bind the independent domain name to the API group, set the Stage parameter to Default(Use X-Ca-Stage to determine the stage), as shown in the following figure.

5. Limits

  • After you modify an environment variable for an API operation, the modification takes effect only after you republish the API operation.

  • A maximum of 50 environment variables can be created in each environment.