Create a Configurable API proxy

Stay organized with collections Save and categorize content based on your preferences.

You're viewing Apigee X documentation.
View Apigee Edge documentation.

With ConfigurablePREVIEW API proxies, Apigee X users can create and deploy a lightweight proxy using declarative configuration, similar to the Kubernetes resource model. This page describes the steps required to create a configurable proxy and deploy it using the new archive-based deployment mechanism.

To learn more about ConfigurablePREVIEW API proxies, see Configurable API proxies.

ConfigurablePREVIEW API proxy development is available only to customers with Apigee paid Subscription orgs. Apigee customers with Pay-as-you-go orgs can create programmable API proxies.

Before you begin

This tutorial assumes that you have already provisioned an Apigee org and installed Apigee. If not, see Introduction to provisioning for the steps required to install and configure Apigee before proceeding.

Before beginning this tutorial, complete the following additional steps:

  1. Confirm that the Cloud SDK is downloaded and installed on your machine.

    Download the Cloud SDK

  2. Update gcloudcomponents:
    gcloud components update
  3. Confirm your Apigee credentials and organization details, as these will be required to provision an environment for the configurable API proxy.

Provision an Apigee environment

Before creating your proxy configuration, you must provision an Apigee environment that supports configurable proxies. An environment is a runtime execution context for the API proxies and shared flows in an organization. You must deploy an API proxy to an environment before it can be accessed. You can deploy an API proxy to a single environment or to multiple environments.

For more detail, see About environments and environment groups.

To create a new environment in the UI:

  1. Open the Apigee UI in a browser.
  2. Select Admin > Environments > Overview in the left navigation menu.

    The UI displays a set of cards, each one representing an existing environment:

    Environment cards

    If this is your first time accessing the Environment view, there will be no environments.

  3. Click +ENVIRONMENT.

    The New environment dialog box displays:

    New Environment dialog

  4. Enter the following information in the New Environment dialog box:
    1. Display name: A friendly name for the environment that is used in the UI. For example, My Test Environment.
    2. Environment name: The programmatic name for the environment. This value will be part of the request URL for your API proxies and should not contain any spaces or other special characters. It can only letters, numbers, and hyphens. For example, my-environment-1.

      The new environment's name cannot be changed after it has been created.

    3. Description (optional): Additional information about the environment that you want to add as a reminder.
    4. Proxy Type (Preview): Select Configurable from the drop-down list of available proxy types.
    5. Deployment type (Preview): Select Archive as the deployment type.

    All fields except Description are required.

  5. Click OK.

    The card displays Pending Provisioning status while Apigee creates the new environment, as the following example shows:

    Pending provisioning label

    There can be a several minute delay before the new environment is provisioned.

    When it's done, the Apigee UI displays the new environment as a card with other environments that you have created:

    Environment cards

Attach the environment to an Apigee instance

After you create a new environment, you must attach the new environment to your Apigee instance for it to be accessible. You can do this through the UI when you create a new instance (if the environment already exists). In this case, if you have previously created an instance, you can attach the new environment using the Instances attachments create api.

For an example of the process, see Create an environment in the command-line provisioning documentation.

For this tutorial, you can use the following command:

operation_name=$(curl -s -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  "" \
  -X POST -H "content-type:application/json"\
  -d '{"environment":"ENV_NAME"}' | jq -r '.name' )


  • PROJECT_ID is the ID of the Cloud project where your Apigee environment is created. This should be the same as your Apigee organization name.
  • INSTANCE_NAME is the name of your Apigee instance.
  • ENV_NAME is the name of the environment where your configurable API proxy will be deployed.

This returns a long running operation. You can poll the operation with the following command until the output shows the operation is done: true.

curl -s -H "Authorization:Bearer $(gcloud auth print-access-token)" \

Configure an environment group

An environment group (sometimes called an envgroup in the Apigee APIs) is the basic mechanism for defining the way requests are routed to individual environments. You define hostnames on your environment groups (not on individual environments), and Apigee routes requests to the environments within a group by using those hostname definitions.

Environments not assigned to groups have no hostnames pointing to them, and therefore they are not accessible. For more information, see Creating environment groups.

To configure an environment group for your new environment:

  1. In the Apigee UI, select Admin > Environments > Groups.
  2. Click +Environment Group:

    Add environment button

    The Add an Environment Group dialog displays.

  3. Enter a name for your new environment group:

    Add environment group

    The name can contain only lower case letters, numbers, and hyphens. In addition, it must start with a letter, be at least two characters long, and cannot end with a hyphen. Valid names include my-env-group and prod2.

  4. Click Add.

    Apigee creates a new environment group. This is usually a very quick operation.

    On a successful operation, Apigee confirms that the group has been created with a banner that looks like the following:

    Group confirmation banner

    Apigee also assigns a default host name to the new group.

  5. (Optional) Assign additional host names to the new group by clicking for that group.

    Apigee displays the Environment group details pane:

    Environment group details

  6. Add host names to the Hostnames field. Each host name must be on a separate line.
  7. Click Save when you're done.

    You can add and remove host names to this list at any time using the same procedure.

Create the proxy archive

To create a ConfigurablePREVIEW API proxy archive:

  1. In your local environment, create a directory to store your Apigee workspace in your local file system. This directory will be the base of your ConfigurablePREVIEW API proxies file structure, as shown below:
    └── src
        └── main
            └── apigee
                ├── apiproxies
                │   ├── <proxy-name>
                │   │   └── config.yaml
                │   ├── <proxy-name>
                │   │   └── config.yaml
                └── environments
                    ├── <env-name>
                    │   ├── deployments.json
                    │   └── targetservers.json
    mkdir -p SOURCE_DIR/src/main/apigee/apiproxies/PROXY_NAME


    • SOURCE_DIR is the name of the archive directory.
    • PROXY_NAME is the name of the configurable proxy.

    For example:

    mkdir -p my-dir/src/main/apigee/apiproxies/my-proxy
  2. Create a new file for your proxy configuration with the following command:
    vi SOURCE_DIR/src/main/apigee/apiproxies/PROXY_NAME/config.yaml

    For example:

    vi my-dir/src/main/apigee/apiproxies/my-proxy/config.yaml

    Your proxy configuration file must use one of the following file names:

    • config.yaml
    • config.json
    • config.yml
  3. Copy the following proxy configuration into the new config.yaml file:
    # config.yaml
    basepath: "/helloworld"
    - id: get-user
      - path_template: "/user"
        method: GET
      uri: ""
  4. Create a deployments.json file using the following command:
    vi SOURCE_DIR/src/main/apigee/environments/ENV_NAME/deployments.json

    For example:

    vi my-dir/src/main/apigee/environments/prod/deployments.json
  5. Copy the following into the new deployments.json file:
  6. {
      "proxies" : ["PROXY_NAME"]

For more examples, see Configurable proxy configuration examples.

Deploy the archive

To deploy an archive to an Apigee environment use the following gcloud command:

gcloud alpha apigee archives deploy \
--organization=PROJECT_ID \
--environment=ENV_NAME \

For example:

gcloud alpha apigee archives deploy \
--organization=my-project \
--environment=prod \

You must specify the Apigee environment in which you want to deploy the archive using the --environment flag. The Apigee environment must be enabled for archive deployments.

For more information about managing archive deployments, see Deploying and managing archives in an Apigee environment.

Check the archive deployment status

To check the archive deployment status, use the gcloud alpha apigee operations command.

The following example shows the archive deployment status for the operation with revision ID 439fa3f7-6aa4-42ad-8b12-3ca912c75d5c is IN_PROGRESS.

gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

The following provides an example of the response:

Using Apigee organization 'myorg'
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.

For additional information on listing archive deployments, viewing details of your deployments, or deleting an environment with an archive deployments, see Deploying and managing archives in an Apigee environment.