apigee_policies

README

Apigee Policies Plugin

This plugin uses custom OpenAPI extensions within the spec to define and insert Apigee policy steps into the generated API proxy bundle.

It's also possible to move the extensions to separate files outside the main Open API Spec. This is useful in cases where you need to share configuration across multiple API Proxies.

How to create an Apigee policy

To create an Apigee policy, use the x-Apigee-Policies extension at the top level. Each policy must have a unique .name property

e.g.

x-Apigee-Policies:
  - FlowCallout:
      .name: FC-Callout
      DisplayName: FC-Callout
      SharedFlowBundle: SharedFlowName

How to insert an Apigee policy

Apigee policies can be inserted at various places within the OpenAPI spec.

1. Within an existing operation in a path
2. At the top-level as a PreFlow policy
3. At the top-level as a PostFlow policy
4. At the top-level as a PostClientFlow policy

When inserting a policy, you use the policy .name to reference it.

Inserting PreFlow Policies

To insert an Apigee PreFlow policy, use the x-Apigee-PreFlow extension.

e.g.

x-Apigee-PreFlow:
  Request:
    - Step:
        Condition: true
        Name: FC-Callout
  Response:
    - Step:
        Condition: true
        Name: FC-Callout

Inserting PostFlow Policies

To insert an Apigee PostFlow policy, use the x-Apigee-PostFlow extension.

e.g.

x-Apigee-PostFlow:
  Request:
    - Step:
        Condition: true
        Name: FC-Callout
  Response:
    - Step:
        Condition: true
        Name: FC-Callout

Inserting PostClientFlow Policies

To insert an Apigee PostClientFlow policy, use the x-Apigee-PostClientFlow extension.

e.g.

x-Apigee-PostClientFlow:
  Response:
    - Step:
        Condition: true
        Name: FC-Callout

Defining extensions in separate files

Each extension can be defined in-line within the OpenAPI spec, or within a separate file.

e.g.

x-Apigee-Policies: 
  $ref: "./apigee-config.yaml#/Policies"

x-Apigee-PreFlow:
  $ref: "./apigee-config.yaml#/PreFlow"

x-Apigee-PostFlow:
  $ref: "./apigee-config.yaml#/PostFlow"

Supported Policies

All Apigee policies are supported.

How to write Apigee policies as YAML

When creating an Apigee policy as YAML, you should be able to take an existing policy's XML representation, and translate it to YAML by following a few basic rules.

• XML elements are represented as YAML fields
• XML elements attributes are represented as YAML fields prepended with a dot .
• XML elements content is represented as YAML fields prepended with .@
• XML elements like this <Simple>Value</Simple> are represented like this Simple: "Value"

See the examples below

• Example 1: XML element containing another XML element

  • <Parent>
      <Child>foo</Child>
    </Parent>
    

    is equivalent to

    Parent:
      Child: foo
    

• Example 2: Simple XML element with no attributes, and scalar content

  • <Field>Content</Field>
    

    is equivalent to

    Field: Content
    

• Example 3: XML element with an attribute

  • <Parent foo="bar" />
    

    is equivalent to

    Parent: 
      .foo: bar
    

• Example 4: XML element with an attribute and scalar content

  • <Parent foo="bar" >Content</Parent>
    

    is equivalent to

    Parent:
      .foo: bar
      .@: Content
    

• Example 5: XML sequence where parent has no attributes

  • <Parent>
      <Child>foo</Child>
      <Child>bar</Child>
    </Parent>
    

    is equivalent to

    Parent:
      - Child: foo
      - Child: bar
    

• Example 6: XML sequence where parent has attributes

  • <Parent attr1="value1" attr2="value2" >
      <Child>foo</Child>
      <Child>bar</Child>
    </Parent>
    

    is equivalent to

    Parent:
      .attr1: value1
      .attr2: value2
      .@:
        - Child: foo
        - Child: bar
    

• Example 7: XML sequence without parent

  • <Root>
      <Child name="foo" />
      <Child name="bar" />
    </Root>
    

    is equivalent to

    Root:
      .@:
        - Child:
          .name: foo
        - Child:
          .name: bar
    

Apigee policies sample YAMLs

Below are several examples for common Apigee policies represented as YAML

Flow Callout

Example Flow Callout policy as YAML.

FlowCallout:
  .async: false
  .name: FC-Callout
  .enabled: true
  .continueOnError: true
  DisplayName: FC-Callout
  SharedFlowBundle: SharedFlowName
  Parameters:
    - Parameter:
        .name: param1
        .value: Literal
    - Parameter:
        .name: param2
        .ref: request.content

is equivalent to

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="true" enabled="true" name="FC-Callout" >
  <DisplayName>FC-Callout</DisplayName>
  <Parameters>
    <Parameter name="param1" value="Literal" ></Parameter>
    <Parameter name="param2" ref="request.content" ></Parameter>
  </Parameters>
  <SharedFlowBundle>SharedFlowName</SharedFlowBundle>
</FlowCallout>

Raise Fault

Example Raise Fault policy represented as YAML

RaiseFault:
  .async: false
  .name: RF-Example
  .enabled: true
  .continueOnError: true
  DisplayName: RF-Example
  IgnoreUnresolvedVariables: true
  ShortFaultReason: false
  FaultResponse:
    - AssignVariable:
        Name: flow.var
        Value: 123
    - Add:
        Headers:
          - Header:
              .name: user-agent
              .@: example
    - Copy:
        .source: request
        Headers:
          - Header:
              .name: header-name
        StatusCode: 304
    - Remove:
        Headers:
          - Header:
              .name: sample-header
    - Set:
        Headers:
          - Header:
              .name: user-agent
              .@: "{request.header.user-agent}"
        Payload:
          .contentType: application/json
          .@: '{"name":"foo", "type":"bar"}'
    - Set:
        ReasonPhrase: Server Error
        StatusCode: 500

is equivalent to

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="true" enabled="true" name="RF-Example" >
    <DisplayName>RF-Example</DisplayName>
    <FaultResponse>
        <AssignVariable >
            <Name>flow.var</Name>
            <Value>123</Value>
        </AssignVariable>
        <Add >
            <Headers>
                <Header name="user-agent" >example</Header>
            </Headers>
        </Add>
        <Copy source="request" >
            <Headers>
                <Header name="header-name" ></Header>
            </Headers>
            <StatusCode>304</StatusCode>
        </Copy>
        <Remove >
            <Headers>
                <Header name="sample-header" ></Header>
            </Headers>
        </Remove>
        <Set >
            <Headers>
                <Header name="user-agent" >{request.header.user-agent}</Header>
            </Headers>
            <Payload contentType="application/json" >{"name":"foo", "type":"bar"}</Payload>
        </Set>
        <Set >
            <ReasonPhrase>Server Error</ReasonPhrase>
            <StatusCode>500</StatusCode>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <ShortFaultReason>false</ShortFaultReason>
</RaiseFault>

Documentation

Index

• Variables
• func ConvertJSONRef2YAMLPath(jsonRef string) string
• func ParseYAMLFile(filePath string) (*yaml.Node, error)
• func ResolveReferences(specModel *libopenapi.DocumentModel[v3high.Document])
• func ResolveYAMLRef(location string) (*yaml.Node, error)
• func ResolveYAMLRefs(node *yaml.Node) (*yaml.Node, error)
• func UnmarshalExtension(extensionName string, extensions map[string]*v1.Extension, target any) error
• type Node
  • func (n *Node) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
• type Plugin
  • func (p *Plugin) ProcessOAS2SpecModel(specModel *libopenapi.DocumentModel[v2high.Swagger]) error
  • func (p *Plugin) ProcessOAS3SpecModel(specModel *libopenapi.DocumentModel[v3high.Document]) error
  • func (p *Plugin) ProcessProxyModel(apiProxy *v1.APIProxy) error

Variables

var ParsedYAMLFiles map[string]*yaml.Node

Functions

func ConvertJSONRef2YAMLPath

func ConvertJSONRef2YAMLPath(jsonRef string) string

func ParseYAMLFile

func ParseYAMLFile(filePath string) (*yaml.Node, error)

func ResolveReferences

func ResolveReferences(specModel *libopenapi.DocumentModel[v3high.Document])

func ResolveYAMLRef

func ResolveYAMLRef(location string) (*yaml.Node, error)

func ResolveYAMLRefs

func ResolveYAMLRefs(node *yaml.Node) (*yaml.Node, error)

func UnmarshalExtension

func UnmarshalExtension(extensionName string, extensions map[string]*v1.Extension, target any) error

Types

type Node

type Node struct {
	XMLName xml.Name
	Attrs   []xml.Attr `xml:"-"`
	Content []byte     `xml:",innerxml"`
	Nodes   []Node     `xml:",any"`
}

func (*Node) UnmarshalXML

func (n *Node) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type Plugin

type Plugin struct {
}

Plugin Custom plugin for handling "x-visibility" OpenAPI extension

func (*Plugin) ProcessOAS2SpecModel

func (p *Plugin) ProcessOAS2SpecModel(specModel *libopenapi.DocumentModel[v2high.Swagger]) error

func (*Plugin) ProcessOAS3SpecModel

func (p *Plugin) ProcessOAS3SpecModel(specModel *libopenapi.DocumentModel[v3high.Document]) error

func (*Plugin) ProcessProxyModel

func (p *Plugin) ProcessProxyModel(apiProxy *v1.APIProxy) error