Apigee Feature Templater v3

🚀 New experimental version v3. The previous version v2 is available in the v2 branch.

Apigee Feature Templater

Apigee Feature Templater (or aft) is an experimental tool providing assisted API authoring through the use of Feature and Template definitions in JSON or YAML formats created and managed through CLI, MCP or REST interfaces. The tool offers a feature-driven approach to API development, potentially scaling up API configuration and authoring to practioners in the organization who are not Apigee proxy developers. This tool is experimental and explores a feature-based approach to API proxy building and configuration.

Check out the wiki for more detailed documentation.

Workflow

1. Apigee proxy experts develop and test technical feature proxies that provide individual, reusable functionalities. This development uses all of the amazing Apigee tooling such as apigeecli, apigee-go-gen, apigelint, Apigee console, etc... Feature proxies have the feature- prefix, making them easy to recognize, import and export.

2. The features are exported using aft to YAML or JSON files, with metadata and parameter configuration information, making it easier for non-experts to understand the capabilities and use the features. A sample repository is in this repo in the ./repository directory.

3. Practioners can use the CLI, MCP agents or web tools using the REST interface to build and publish APIs using the feature building-blocks.

Getting started

1. To begin let's install the tool in our local shell.
``sh

install apigee-templater with npm

npm i apigee-templater -g

or update to the latest version

npm update apigee-templater -g
`

2. Next let's create an empty template for an AI Gateway API that will proxy both Gemini and Mistral endpoints from Vertex AI, along with API key authorization.

`sh


create an empty template

aft AI-Gateway-v1.yaml

apply Gemini and Mistral features, -i means input file and -a means apply feature

aft -i AI-Gateway-v1.yaml -a proxy-gemini
aft -i AI-Gateway-v1.yaml -a proxy-mistral
aft -i AI-Gateway-v1.yaml -a auth-key-header

when applying features with -a, we can use file or https paths,

or names from the ./repository/features directory.

`

Notice now that our AI-Gateway-v1.yaml file includes the configuration parameters from the three features, as well as the endpoints. This is a Template file which when deployed will merge all features into a complete proxy.

`yaml
type: template
description: API template for AI-Gateway-v1
features:
- proxy-gemini.5vorvj
- proxy-mistral.4z32
- auth-key-header.pimaw
parameters:
# ... parameters from all features, these can be passed during
# deployment to customize the features ...
- name: auth-key-header.pimaw.API_KEY_HEADER_NAME
description: The header where the api key is checked.
default: x-api-key
examples:
- x-api-key
- x-apikey
endpoints:
- name: 5vorvj-gemini
basePath: "{BASE_PATH}"
routes:
- name: default
target: 5vorvj-gemini
- name: 4z32-mistral
basePath: "{BASE_PATH}"
routes:
- name: default
target: 4z32-mistral
targets:
- name: 5vorvj-gemini
url: https://{propertyset.gemini.GEMINI_PATH}
auth: GoogleAccessToken
scopes:
- https://www.googleapis.com/auth/cloud-platform
- name: 4z32-mistral
url: https://{propertyset.mistral.MISTRAL_PATH}
auth: GoogleAccessToken
scopes:
- https://www.googleapis.com/auth/cloud-platform
`

3. Export the Template to an Apigee org.

`sh
PROJECT_ID=YOUR_PROJECT_ID
aft -i AI-Gateway-v1.yaml -o $PROJECT_ID:AI-Gateway-v1
`

Open the Apigee console and deploy the AI-Gateway-v1 proxy to an Apigee environment, you can use both Gemini and Mistral at the v1/gemini and v1/mistral paths, each with API key authorization. You could also export / import to an Apigee ZIP bundle, and upload & deploy using your tool of choice.

Concepts

$3

A feature JSON or YAML file models an individual functionality that can be reused in many proxies. A feature file also includes documentation, input parameter descriptions, as well as the complete feature logic, including resources and policies, completely self-contained. You can import/export Apigee proxies to feature files, making it easy to leverage the Apigee console or existing tooling for building features.

$3

A feature file can be created from an Apigee proxy ZIP, folder, or remote from an org. The -f feature at the end is important because it says convert the proxy format to a feature format with input parameter configuration, making it more reusable.
`yaml

import extracted apigee proxy (from ./test/proxies/DATA-HelloWorld-v1)

aft -i ./test/proxies/DATA-HelloWorld-v1 -o DATA-HelloWorld-v1.yaml -f feature

OR import from an Apigee org

aft -i GCP_PROJECT_ID:Feature-DATA-HelloWorld-v1 -o DATA-HelloWorld-v1.yaml -f feature
`
The resulting example feature file contains all of the proxy logic, along with any propertysets converted into input parameters that can be configured. This feature takes a configurable message and adds it to the response payload, if it exists.
`yaml
name: DATA-HelloWorld-v1
type: feature
description: Proxy for DATA-HelloWorld-v1
parameters:
- name: MESSAGE
displayName: MESSAGE
description: Configuration input for MESSAGE
default: Hello world!
examples: []
endpointFlows:
- name: PostFlow
mode: Response
steps:
- name: JS-AddHelloWorld
targetFlows: []
endpoints: []
targets: []
policies:
- name: JS-AddHelloWorld
type: Javascript
content:
Javascript:
_attributes:
continueOnError: "false"
enabled: "true"
timeLimit: "200"
name: JS-AddHelloWorld
DisplayName:
_text: JS-AddHelloWorld
Properties: {}
ResourceURL:
_text: jsc://hello-world.js
resources:
- name: hello-world.js
type: jsc
content: |-
var responseObject = response.content.asJSON;

if (responseObject) {
var message = context.getVariable("request.queryparam.message");
if (!message)
message = context.getVariable("propertyset.helloworld.MESSAGE");
if (!message)
message = "Hello world!";
responseObject["message"] = message;
context.setVariable("response.content", JSON.stringify(responseObject))
}
- name: helloworld.properties
type: properties
content: |
MESSAGE={MESSAGE}
`


Templates

Feature template files bundle multiple features with configuration parameters and documentation, making it easier to manage for proxy deployments.

$3

An empty feature template file can be created using aft -o FILENAME which simply creates an empty output file. We could also add -f feature, however this is the default and is not needed for new files.

`sh


create empty feature template file

aft -o HttpBin-Proxy-v1.yaml

apply HttpBin and HelloWorld features, -i means input file,

and is the default -o output if nothing else is set

aft -i HttpBin-Proxy-v1.yaml -a ./repository/features/PROXY-HttpBin-v1.yaml
aft -i HttpBin-Proxy-v1.yaml -a ./repository/features/DATA-HelloWorld-v1.yaml
`
Here is the resulting feature template file after applying the above features.
`yaml
name: HttpBin-Proxy-v1
type: template
description: API template for HttpBin-Proxy-v1
features:
- repository/features/PROXY-HttpBin-v1.yaml
- repository/features/DATA-HelloWorld-v1.yaml
parameters:
- name: DATA-HelloWorld-v1.MESSAGE
displayName: MESSAGE
description: Configuration input for MESSAGE
default: Hello world!
examples: []
endpoints:
- name: httpbin
basePath: /v1/httpbin
routes:
- name: default
target: httpbin
targets:
- name: httpbin
url: https://httpbin.org
`
This feature template file references two features, and also includes all parameters, endpoints and targets from all features into one bundle that can be deployed. If there would have been a conflict, it would have been output as a warning (with the last conflict winning).

Export this feature template to an Apigee org, or convert to an Apigee zip and deploy via apigeecli.

`sh


export to an apigee org

aft -i HttpBin-Proxy-v1.yaml -o GCP_PROJECT_ID:HttpBinProxy-v1 -t $(gcloud auth print-access-token)

export to an Apigee zip

aft -i HttpBin-Proxy-v1.yaml -o HttpBinProxy-v1.zip
`

REST & MCP server

The above examples all use the aft CLI tool to work with features, however we can also use MCP or REST. After cloning this repository you can start the REST & MCP server using npm.
`sh

install dependencies

npm i

start server

npm start
``
Sample REST calls can be found in the wiki.

Test the MCP server in a sample ADK agent here.

Sample agent requests:

> List all proxies in the apigee org apigee-prod13.

> Describe the proxy Llama-v1 in the org apigee-prod13.

> Import the proxy Llama-v1 to a feature with the name AI-Llama-v1.

> Create a new template named AI-Proxy-v1 with the features AI-Llama-v1, AI-Gemini-v1 and Auth-Key-Header-v1 applied.

> Export a proxy from the template AI-Proxy-v1 and deploy it to the apigee org apigee-prod13 and environment dev.

Limitations

Currently these features are not yet supported:
- Target fault rules and default fault rule are not yet converted. Endpoint faults are converted.
- The MCP service does not yet use parameters when applying features, so currently only default values are used.

Contributing

See the contributing instructions to get started.

License

All solutions within this repository are provided under the
Apache 2.0 license.
Please see the LICENSE file for more detailed terms and conditions.

Disclaimer

This repository and its contents are not an official Google product.