To keep development, staging, and production traffic isolated, API Gateway provides three built-in environments—TEST, PRE, and RELEASE—and lets you create custom environments that map the same API configurations to different backend URLs.
How environments work
API Gateway routes each API request to a backend URL based on the target environment. The same API configuration can point to a different backend URL in each environment, so you can validate changes safely before they reach production.
To use environments, complete these steps:
(Optional) Create a custom environment: Use the API Gateway console to create environments beyond the three built-in ones.
Configure your backend service: Set a different backend URL for each environment so API requests are routed to the correct backend.
Configure your client: Clients must target a specific environment. Bind a separate domain name to each environment, or require clients to send the X-Ca-Stage header in their requests.
Create an environment
API Gateway provides three built-in environments: TEST, PRE, and RELEASE. If these environments do not meet your requirements, create a custom environment.
Log on to the API Gateway console to view available environments.
-
Click Create Environment. In the Create Environment dialog box, fill in the following fields. The environment name and alias must be globally unique.
Environment Name: 2–10 characters; uppercase letters and digits only; must start with an uppercase letter.
Alias: The display name of the environment. 2–50 characters; letters, digits, and underscores (_) allowed.
Description: A brief description of the environment.
Click Confirm to create the environment.
Use environments
Configure a backend service with environment URLs
Manage your API backend applications using backend services, then configure a different URL for each environment. For setup instructions, see steps 1 and 2 in Use a backend service to create and manage APIs.
Publish APIs to an environment
After creating and configuring a backend service, create an API so clients can call it. For instructions on creating and debugging an API, see steps 3, 4, and 5 in Use a backend service to create and manage APIs. You can publish the API to any environment, including TEST, PRE, RELEASE, and any custom environments you have created.
Use the X-Ca-Stage header to target an environment
When debugging, you can test your API 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 and set the Environment parameter to Default (X-Ca-Stage), clients can use the X-Ca-Stage header to target a specific environment.
To call the API in the RELEASE environment, omit the X-Ca-Stage header.
To call the API in the PRE environment, add the X-Ca-Stage: PRE header to each request.
To call the API in the TEST environment, add the X-Ca-Stage: TEST header to each request.
To call the API in a custom environment, add the X-Ca-Stage: environment name header, replacing environment name with the actual name of the environment.
Bind a domain name to an environment
Bind a dedicated domain name to each environment so clients can call APIs without specifying the X-Ca-Stage header. Select the target environment when binding an independent domain name to an API group. For instructions, see Bind a custom domain name to allow API calls.
Domain name binding takes precedence over the X-Ca-Stage header. API Gateway routes requests based on the binding configuration, regardless of any X-Ca-Stage header value the client sends.
Delete an environment
Log on to the API Gateway console to view available environments.
Find the environment you want to delete and click Delete in the Actions column.
Built-in environments cannot be deleted.
Environments with associated backend services cannot be deleted.
Environments with published APIs cannot be deleted.