Configuring a proxy with YAML

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Beta

This feature is in beta and is subject to change. It is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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: 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: 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 template + feature files
  |  gcloud beta 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.

A minimal example

The following template defines a proxy that composes two features—one that adds a backend target and one that adds a response message:

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

Every referenced feature file must be in the same directory as the template. For a full, runnable example and the feature files it uses, see Create an API proxy from a YAML template.

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 Vertex AI 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 can only reference feature files that are in the same directory. Referencing features by URL or from a shared catalog is not supported.
• Parameter values use their defaults. Features can define parameters, but parameter values resolve to the default defined in the feature. There is no command-line flag to override parameter values at import time.
• 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
• API proxy YAML configuration reference
• Understanding APIs and API proxies