This topic describes how to manage environments in API Gateway. Specifically, this topic describes how to create a custom environment, use the environment to isolate backend services, and delete the environment.
1. What is environment management?
Environment management refers to the management of environments that are created and maintained for different purposes in different stages, such as software development, testing, and deployment. Typically, environments fall into three categories: testing, staging, and production. Proper management of environments helps ensure the good quality, stability, and security of software and facilitate teamwork.
API Gateway provides three built-in environments: TEST, PRE, and RELEASE. Aside from that, API Gateway allows you to create and use custom environments based on your business requirements. You can isolate backend services of different R&D stages by environment based on the same set of API configurations. This improves your R&D efficiency and API manageability.
Proper use of API environments typically involves three steps:
(Optional) Create and maintain custom environments: You can use the API Gateway console to create and maintain your own environments.
Configure your backend service: You can configure different settings for your backend service in different environments, such as the testing, staging, and production environments. This allows API requests to be routed to different backend URLs.
Configure your client: Your users must explicitly specify the URL to send a request on their client. You can either bind different domain names to different API groups or require your users to add the X-Ca-Stage header in their API requests.
2. Create an environment
API Gateway provides three built-in environments for you to use: TEST, PRE, and RELEASE. If these environments do not meet your business requirements, you can create your own environments.
Log on to the API Gateway console to view available environments.
If you want to create an environment, click Create Environment. In the Create Environment dialog box, enter an environment name, alias, and description. The environment name and alias must be globally unique.
Environment Name: The name must be 2 to 10 characters in length and can contain uppercase letters and digits. The name must start with an uppercase letter.
Alias: the display name of the environment. The alias must be 2 to 50 characters in length and can contain letters, digits, and underscores (_).
Description: the description of the environment.
Click Confirm to complete the environment creation.
3. Use the environment
3.1 Create a backend service and configure an environment URL for it
We recommend that you manage your backend applications of APIs by using backend services. You can configure different environment URLs for a backend service to distinguish applications in different environments. For more information, see steps 1 and 2 in Use a backend service to create and manage APIs.
3.2 Publish APIs to the environment
After you create and configure a backend service, you need to create an API for the backend service for your users to call. For more information about how to create and debug an API, see steps 3, 4, and 5 in Use a backend service to create and manage APIs. You can publish your API to all available environments, including the system provided TEST, PRE, and RELEASE environments and your custom environments.
3.3 Use the X-Ca-Stage header to call an API in a specified environment
When debugging your API, you can trial call the API by using the system provided second-level domain name or the X-Ca-Stage request header. If you have bound an independent domain name to the API group to which your API belongs and the Environment parameter is set to Default (X-Ca-Stage) when you performed the binding, your users can use the X-Ca-Stage header to specify the environment to which they want to send API requests.
To call the API in the RELEASE environment, users do not need to specify the X-Ca-Stage parameter in API requests.
To call the API in the PRE environment, users must add the X-Ca-Stage: PRE header to each API request.
To call the API in the TEST environment, users must add the X-Ca-Stage: TEST header to each API request.
To call the API in a custom environment, users must add the X-Ca-Stage: environment name header to each API request. They must replace environment with the actual environment name.
3.4 Bind an independent domain name to a specific environment
You can bind a separate domain name for each environment. This way, your users do not need to use the X-Ca-Stage header to specify the environment to call an API. You can select the desired environment when you bind an independent domain name to an API group. For more information about how to bind an independent domain name, see Bind a custom domain name to allow API calls.
The domain name binding takes precedence over the X-Ca-Stage header. In other words, even if users specify the X-Ca-Stage header in their requests, API Gateway routes the requests based on the binding configuration.
4. Delete an environment
Log on to the API Gateway console to view available environments.
Find the environment that you want to delete and click Delete in the Actions column.
Built-in environments cannot be deleted.
If an environment has associated backend services, the environment cannot be deleted.
If an environment has published APIs, the environment cannot be deleted.