Create an API proxy from a YAML template

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This page shows you how to define an API proxy as an Apigee Feature Template in YAML and deploy it with the Google Cloud CLI. You first build a simple proxy, and then build a more complete example that fronts a Gemini model.

For background, see Configuring a proxy with YAML. For the full schema, see API proxy YAML configuration reference.

Before you begin

  • For Part 2 only: enable the Agent Platform API in the Google Cloud project that hosts the model:

    gcloud services enable aiplatform.googleapis.com \
        --project=PROJECT_ID

    Replace PROJECT_ID with the ID of the project that hosts the model, for example my-apigee-project. This walkthrough uses the project of your Apigee organization. Part 1 doesn't need this API. You don't need to choose a region, because the template uses the global endpoint. It can take a short time for the API to become active after you enable it.

  • Install and initialize the Google Cloud CLI.
  • Have an Apigee organization and at least one environment. Note the organization and environment names; the examples use ORG and ENV as placeholders (see Placeholders used on this page). The AI gateway in Part 2 additionally requires an Intermediate or Comprehensive environment (not a Base environment); see Apigee environment types.
  • Make sure you have the required permissions:
    • To import (create) an API proxy: the API Admin role (roles/apigee.apiAdmin), or an equivalent role that grants apigee.proxies.create.
    • To deploy an API proxy: Environment Admin (roles/apigee.environmentAdmin) on the target environment, and API Reader (roles/apigee.apiReaderV2) at the project level.
    • To create the API product, developer, and app that produce the API key in Part 2, Step 6: API Admin (roles/apigee.apiAdmin) and Developer Admin (roles/apigee.developerAdmin). For the full list of roles, see Apigee roles.

Placeholders used on this page

Replace each placeholder in the commands with your own value. Most values already exist and you look them up. You choose SA_NAME yourself, and some values are generated as you work through the steps.

Placeholder Source Description
ORG Look up Your Apigee organization name. This is usually the same as PROJECT_ID. To list the organizations you can access, run gcloud apigee organizations list.
ENV Look up An environment in your organization, for example test. Part 1, Step 4 shows how to list them.
PROJECT_ID Look up The ID of the Google Cloud project that holds your Apigee organization, for example my-apigee-project. To print the active project, run gcloud config get project.
HOSTNAME Look up A hostname of an environment group that contains ENV, for example api.example.com. Part 1, Step 5 shows where to find it.
SA_NAME You choose A name for the service account that you create in Part 2, Step 3, for example apigee-ai-gateway.
PROJECT_NUMBER Look up The project number of PROJECT_ID, for example 123456789012. Part 2, Step 3 shows the command that prints it.
REGION You choose Optional. A region that serves your model, for example us-central1. You need it only if you switch the gemini-target feature to a regional endpoint.
REVISION Generated The proxy revision number that the import command prints in Part 2, Step 4, for example 1.
API_KEY Generated The API key that Apigee generates when you register a developer app in Part 2, Step 6.

Part 1: Create a simple API proxy

In this section, you create a proxy that forwards requests to the Apigee mock target service and enforces a rate limit.

Step 1: Create the template

A template is the file you deploy. It defines your proxy's base path, routes, and backend target, and lists the features to include.

Create a project directory for your templates, with a features subdirectory for the features they use:

mkdir -p proxy-templates/features
cd proxy-templates

When you finish this part, the project directory looks like this:

proxy-templates/
  hello-proxy.yaml
  features/
    spike-arrest.yaml

In the proxy-templates directory, create a file named hello-proxy.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: hello-proxy
type: template
description: A simple proxy to the Apigee mock target, protected by a rate limit.
features:
- ./features/spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

This template defines:

  • An endpoint with the base path /hello. Clients call the proxy at this path.
  • A route that sends requests to the target named default.
  • A target that points to the backend URL.
  • A feature, spike-arrest.yaml, which you create next.

Step 2: Create the feature

A feature is a reusable unit of configuration that holds policies. A template can't contain policies directly, so the rate-limiting policy lives in a feature.

In the features directory, create a file named spike-arrest.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: spike-arrest
displayName: Spike Arrest
type: feature
description: Protects the backend by smoothing traffic spikes.
categories:
- traffic
parameters:
- name: RATE
  displayName: RATE
  description: Maximum request rate, for example 30ps (per second) or 100pm (per minute).
  default: 30ps
  examples:
  - 30ps
  - 100pm
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: SA-SpikeArrest
policies:
- name: SA-SpikeArrest
  type: SpikeArrest
  content:
    SpikeArrest:
      metadata:
        name: SA-SpikeArrest
        enabled: "true"
        continueOnError: "false"
      DisplayName: SA-SpikeArrest
      Rate: "{RATE}"

This feature:

  • Defines a SpikeArrest policy that limits the request rate.
  • Uses defaultEndpoint.flows to add the policy to the request PreFlow, so it runs on every request.
  • Declares a parameter, RATE, whose default (30ps) is substituted for {RATE} when the proxy is compiled.

Step 3: Import the proxy

Import the template to create an API proxy revision. Run this command from the proxy-templates directory, which contains the template:

gcloud apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

The CLI compiles the template and its feature into an API proxy bundle, uploads it, and prints the new proxy revision. Importing creates a revision but does not deploy it.

Step 4: Deploy the proxy

List the environments in your organization:

gcloud apigee environments list --organization=ORG

The command prints the environment names. Pick one to use as ENV, and deploy the revision to it:

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

By default, this command deploys the latest revision. To deploy a specific revision, pass its number as the first argument, for example gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. If a different proxy is already deployed at the same base path, add --override to replace it with zero downtime.

Step 5: Call the proxy

To call the deployed proxy over the network, your environment must be attached to an environment group that has a routable hostname. If you just created your organization, confirm this is set up before you call the proxy; see About environments and environment groups.

Find the hostname of an environment group that contains your environment:

  1. In the Google Cloud console, go to Apigee > Management > Environments.
  2. Select the Environment groups tab.
  3. Find the environment group that contains your environment, and copy a value from its Hostnames column.

Call the proxy at that hostname, using the base path from your template:

curl https://HOSTNAME/hello

Replace HOSTNAME with the hostname you copied. A successful response comes from the mock target service.

Part 2: Build an AI gateway for Gemini

This section builds a more complete proxy: an AI gateway that forwards requests to a Gemini model on Gemini Enterprise Agent Platform, enforces a rate limit, and requires an API key. It uses one template, three features, and a service account.

Unlike the simple proxy in Part 1, this proxy calls a Google Cloud service (Agent Platform). The gemini-target feature uses auth: GoogleAccessToken, so Apigee attaches a Google OAuth token to each request to Agent Platform. That token is issued for a service account that you create and then provide when you deploy the proxy, so this part adds a step to create that service account (Step 3).

Before you start, make sure that the Agent Platform API is enabled in the project that hosts the model, as described in Before you begin. You don't need to have used Agent Platform before.

In Part 2, PROJECT_ID is the ID of your Apigee organization's project, for example my-apigee-project. Part 2 uses this one project throughout: you enable the API in it, create the service account in it, and set it as the template's MODEL_PROJECT_ID value.

Step 1: Create the template

In the proxy-templates directory from Part 1, create a file named ai-gateway.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: ai-gateway
type: template
description: AI gateway that fronts a Gemini model with throttling and API key enforcement.
features:
- ./features/spike-arrest.yaml
- ./features/verify-api-key.yaml
- ./features/gemini-target.yaml
parameters:
- name: MODEL_PROJECT_ID
  default: PROJECT_ID
- name: MODEL
  default: gemini-3.8-flash
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

The parameters list sets values for the parameters that the gemini-target feature declares, which you create in the next step. Replace PROJECT_ID with the project ID that you used to enable the API, for example my-apigee-project.

Step 2: Create the features

The template uses three features. Reuse the spike-arrest.yaml feature from Part 1, and create the other two in the features directory. When you finish this step, the project directory looks like this:

proxy-templates/
  hello-proxy.yaml
  ai-gateway.yaml
  features/
    spike-arrest.yaml
    verify-api-key.yaml
    gemini-target.yaml

Create features/verify-api-key.yaml to require an API key in the x-api-key header:

gateway: apigee
schemaVersion: 1.0.0
name: verify-api-key
displayName: Verify API Key
type: feature
description: Requires a valid API key in the x-api-key request header.
categories:
- security
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: VA-VerifyAPIKey
policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

Create features/gemini-target.yaml to route to a Gemini model, authenticated with a Google access token:

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on the Gemini Enterprise Agent Platform, authenticated with a Google access token.
categories:
- llm
parameters:
- name: MODEL_PROJECT_ID
  displayName: Model Project ID
  description: Google Cloud project that hosts the Gemini model. Supplied by the template; no default.
- name: MODEL
  displayName: Model
  description: The Gemini model to route to.
  default: gemini-3.8-flash
  examples:
  - gemini-3.8-flash
  - gemini-4-argon
targets:
- name: gemini
  url: https://aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/global/publishers/google/models/{MODEL}:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

The gemini-target feature declares two parameters and substitutes them into the target URL:

  • MODEL_PROJECT_ID: the Google Cloud project that hosts the model. It has no default, so the template must set it to your project ID.
  • MODEL: the Gemini model to call. The feature's default is gemini-3.8-flash.

When the CLI compiles the template, it resolves each parameter as follows:

  1. If the template's parameters list has an entry with the same name and a non-empty default, the CLI uses that value.
  2. Otherwise, the CLI uses the feature's default.
  3. If neither sets a value, the CLI replaces {name} with an empty string. The import doesn't report an error, so a missing MODEL_PROJECT_ID produces a target URL with no project ID.

There is no command-line flag to set parameter values when you import. To use a different project or model, edit its value in the template's parameters list and import the template again.

The gemini-target feature uses auth: GoogleAccessToken so that Apigee attaches a Google access token to each request to Agent Platform.

The URL uses the global endpoint (host aiplatform.googleapis.com and locations/global), which serves gemini-3.8-flash and routes requests to available capacity across regions. With the global endpoint, you don't need to choose a region.

To call a different model, set MODEL in the template's parameters list to the model's ID. To list the Gemini models that you can call, run:

gcloud ai model-garden models list --model-filter=gemini

Each value in the MODEL_ID column looks like google/gemini-3.8-flash@default. Set MODEL to the part between google/ and @, such as gemini-4-argon. The model's card in Model Garden in the Google Cloud console shows the same ID. To check that a model supports the global endpoint, see the Global tab in Google model endpoint locations.

If you need to control which region processes requests, replace the url line in features/gemini-target.yaml with the regional form, which puts the region in both the host and the path:

  url: https://REGION-aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/REGION/publishers/google/models/{MODEL}:generateContent

Replace REGION with a region that serves your model, as listed in the same Google model endpoint locations tables. For when to avoid the global endpoint, see Global endpoint.

Step 3: Create a service account for the proxy

Because the gemini-target feature uses auth: GoogleAccessToken, the deployed proxy calls Agent Platform as a service account. Create that service account, give it access to Agent Platform, and let the Apigee service agent use it. You provide this service account when you deploy the proxy in Step 5. For more detail, see Using Google authentication.

  1. Create a user-managed service account in the same Google Cloud project as your Apigee organization. (The Compute Engine default service account is not accepted.) For other ways to create one, see Creating and managing service accounts.
    gcloud iam service-accounts create SA_NAME \
        --project=PROJECT_ID \
        --display-name="Apigee AI gateway"

    Pick a descriptive name for SA_NAME, for example apigee-ai-gateway. The command creates the service account SA_NAME@PROJECT_ID.iam.gserviceaccount.com, for example apigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com.

  2. Grant the service account access to the backend it calls. For an Agent Platform target, grant the Agent Platform User role (roles/aiplatform.user):
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/aiplatform.user"

    If your project's IAM policy already contains conditional role bindings, add --condition=None to this command.

  3. Let the Apigee service agent mint tokens for the service account by granting it the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on the service account:
    gcloud iam service-accounts add-iam-policy-binding \
        SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --project=PROJECT_ID \
        --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \
        --role="roles/iam.serviceAccountTokenCreator"

    To find PROJECT_NUMBER, run gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

Step 4: Import the proxy

Import the template to create an API proxy revision. Run this command from the proxy-templates directory, which contains the template:

gcloud apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

Note the revision number in the command output; you need it in Step 5. To print just the revision number, add --format="value(revision)" to the import command.

Step 5: Deploy the proxy with the service account

Deploying the AI gateway differs from the simple proxy in Part 1 in two ways:

  • You must provide the service account you created in Step 3. If you deploy without one, the deployment fails with a MISSING_SERVICE_ACCOUNT error.
  • You must deploy to an Intermediate or Comprehensive environment. This proxy uses an extensible policy, which a Base environment does not support; deploying to one fails with the error Extensible proxy can not be deployed to a base environment. The gcloud apigee environments list command doesn't print the environment type. To check it, in the Google Cloud console, go to Apigee > Management > Environments. See Apigee environment types.

Deploy the revision and pass the service account with --service-account. Replace REVISION with the revision number from Step 4:

gcloud beta apigee apis deploy REVISION \
    --api=ai-gateway \
    --environment=ENV \
    --organization=ORG \
    --service-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com

Deployment is asynchronous. To check its status, which reports PROGRESSING until it becomes READY, run:

gcloud apigee deployments describe \
    --api=ai-gateway \
    --environment=ENV \
    --organization=ORG \
    --format="value(state)"

When the proxy is compiled, the spike-arrest and verify-api-key features add their policies to the request PreFlow (rate limiting first, then the API key check), and the gemini-target feature adds the Agent Platform backend. After the deployment completes, the proxy authenticates to Agent Platform as your service account.

Step 6: Get an API key

The verify-api-key feature rejects any request that doesn't carry a valid API key, so you need a key before you can call the proxy. An API key is a credential of a developer app that is associated with an API product containing this proxy. Complete the following tasks, which are described in Publishing overview:

  1. Create an API product that includes the ai-gateway proxy. In the product form, enter the following, and then click Save:
    • Name and Display name: any value, for example ai-gateway-product.
    • Environment: the environment you deployed the proxy to (ENV).
    • Access: Public. Leave Automatically approve access requests selected so that the API key is approved when you register the app.
    • In the Operations section, click + ADD AN OPERATION and set these fields:
      • API proxy: ai-gateway.
      • Path: /. Requests go to the proxy's base path, /v1/gemini, with nothing after it. The path / matches the base path; /** matches only paths below it, so a request to /v1/gemini fails with the error oauth.v2.InvalidApiKeyForGivenResource. See Configuring resource paths.
      • Methods: POST.
    • Leave API quota limit, LLM token quota limit, the operation's Quota, and the LLM Operations section empty. The spike-arrest feature in the proxy enforces the rate limit.
  2. Register an app developer.
  3. Register a developer app and select the API product when you create the app, so that the new key is associated with the product from the start.

Registering the app generates the key. To retrieve it, see Viewing an API key and secret.

Step 7: Call the proxy

Find your environment group's hostname as described in Part 1, Step 5, then call the proxy at the base path /v1/gemini. Pass the API key in the x-api-key header, and send a Gemini generateContent request body:

curl -X POST https://HOSTNAME/v1/gemini \
    -H "x-api-key: API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'

Replace HOSTNAME with your environment group hostname and API_KEY with the key from Step 6. A successful response is the model's JSON output. Omitting the key returns an authorization failure from the VerifyAPIKey policy, which confirms that the verify-api-key feature is in effect. For other ways to pass a key, see Submitting a request with a valid API key.

Next steps