*This page
applies to **Apigee** and **Apigee hybrid**.*


*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*
![](https://fonts.gstatic.com/s/i/googlematerialicons/help/v13/gm_grey-24dp/1x/gm_help_gm_grey_24dp.png)

You can define an Apigee API proxy in YAML and deploy it with the
Google Cloud CLI, as an alternative to authoring the traditional XML proxy
bundle. You describe a proxy's endpoints, routes, policies, and backend targets
in YAML files called *Apigee Feature Templates*, and Apigee
compiles them into a standard API proxy bundle for you.

Because the result is an ordinary Apigee API proxy bundle, a proxy
that you build this way runs on the same Apigee runtime, with the same
policies and behavior as a proxy that you build in the Apigee UI or
from an XML bundle.

> [!NOTE]
> **Note:** This page describes authoring proxies with YAML. It does not change how existing proxies work. When you troubleshoot a proxy in the Apigee UI, you still see the generated XML configuration, not the YAML source.

## Why use YAML to define proxies

The traditional Apigee API proxy format is a ZIP archive of XML
files. YAML offers an alternative that many developers find faster to read,
write, and review, and that works well with AI-assisted and agentic tooling.
Apigee Feature Templates are designed for:

- **API developers and architects** who prefer a concise, declarative format and want to keep proxy configuration in source control.
- **AI practitioners** who want a standardized way to put an Apigee gateway in front of a model backend.
- **Platform and DevOps teams** who want to package reusable pieces of proxy configuration and apply them consistently across many proxies.

## Key concepts

Apigee Feature Templates use three document types. Each is a YAML file
identified by its `type` field.

| Document type | `type` value | Purpose |
|---|---|---|
| Template | `template` | The entry point that you deploy. A template composes one or more features and defines the proxy's endpoints and routes. |
| Feature | `feature` | A reusable unit of configuration---such as an authentication check, a rate limit, or a backend target---that you include in a template. Features hold the policies and resources. |
| Proxy | `proxy` | The fully resolved proxy that the CLI produces when it compiles a template with its features. While typically an intermediate output generated by the CLI, you can also import a proxy file directly to be translated into an API proxy bundle. |

You author **templates** and **features** . Apigee generates
the **proxy** for you during compilation.

> [!NOTE]
> **Note:** A template composes features but does not contain policies or resources of its own. To add policies---such as security, traffic management, or message transformation---you define them in features and reference those features from your template.

## How it works

When you import a template, the Google Cloud CLI performs the following steps
locally, then uploads the result to Apigee:

1. **Compile.** The CLI reads your template and the feature files it references, merges them, and produces a single proxy definition.
2. **Convert.** The CLI converts the proxy definition into a standard Apigee API proxy bundle (the ZIP of XML files that Apigee expects).
3. **Import.** The CLI uploads the bundle to Apigee, which creates a new API proxy *revision*.

Importing a proxy does not make it live. As a separate step, you
**deploy** the revision to an environment, exactly as you would for any other
API proxy:

```yaml
YAML template + feature files
  |  gcloud apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)
```

For step-by-step instructions, see
[Create
an API proxy from a YAML template](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/configure-proxy-with-yaml-example).

## A minimal example

The following template defines a proxy with one endpoint and one backend
target, and adds a rate limit by composing one feature,
`spike-arrest.yaml`:

```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
```

Each entry in `features` is a path to a local feature file,
relative to the directory that contains the template. In this example, the
feature file is in a `features` subdirectory next to the template.
For the full walkthrough, including the `spike-arrest.yaml` feature
file, see
[Create
an API proxy from a YAML template](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/configure-proxy-with-yaml-example).

## What you can do

- Define a proxy's endpoints, base paths, routes, flows, and backend targets in YAML.
- Package reusable policies and resources as features and compose them in a template.
- Add backend authentication for Google Cloud targets (for example, a Google access token for a Gemini Enterprise Agent Platform backend).
- Import a template as a new API proxy revision with the Google Cloud CLI, then deploy it with the standard deploy command.

## Limitations

Keep the following in mind when you author templates and features:

- **Features are local files.** A template references each feature by a path relative to the directory that contains the template. Referencing features by URL or from a shared catalog is not supported.
- **Parameter values are set in the template.** A feature parameter takes its value from the template's `parameters` list, or from the feature's `default` if the template doesn't set one. The CLI replaces a parameter that has no value with an empty string and doesn't report an error. There is no command-line flag to set parameter values at import time; to change a value, edit the template and import it again.
- **JSONPath parameters are not supported.** A parameter that uses a `paths` (JSONPath) expression causes compilation to fail.
- **Tests are not supported.** A `tests` section is accepted by the schema but is ignored and not included in the generated bundle.
- **The schema is strict.** Unknown fields cause an error. Only `gateway: apigee` and `schemaVersion: 1.0.0` are supported.
- **Troubleshooting uses the generated XML.** The Apigee UI and runtime work with the generated bundle. There is no round-trip back to your YAML source in the UI.

## Next steps

- [Create
  an API proxy from a YAML template](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/configure-proxy-with-yaml-example)
- [API
  proxy YAML configuration reference](https://docs.cloud.google.com/apigee/docs/api-platform/reference/api-proxy-yaml-configuration-reference)
- [Understanding
  APIs and API proxies](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/understanding-apis-and-api-proxies)