Custom Plugin¶

Overview¶

Custom Plugin in Yappes lets you run custom Go code at the API Gateway during the On Request or On Response phase of an API call.

This feature helps organizations to:

Add gateway-level logic without changing backend services
Run custom request or response handling before traffic reaches or leaves the backend
Reuse the same plugin policy across multiple subscription endpoints
Combine gateway policies with lightweight custom code where built-in policies are not enough

When applied at the API or subscription level, Custom Plugin executes Go code at the Yappes Gateway during the selected execution phase.

When to Use Custom Plugin¶

Use Custom Plugin when:

You need custom gateway logic such as header manipulation, lightweight payload changes, or conditional checks
Logic should run at the gateway without deploying changes to backend services
You want separate On Request and On Response plugins per endpoint
A reusable subscription-level plugin should be attached to specific consumer endpoints

When Not to Use Custom Plugin¶

Avoid using Custom Plugin in the following scenarios:

A built-in policy already covers the requirement (for example Transformation Policy, Schema Validation, or Threat Protection policies)
Complex business logic belongs in backend services rather than the gateway
You need full access to system-level Go packages (os, exec, syscall, and similar are blocked)

Prerequisites¶

Before configuring Custom Plugin policies, ensure the following requirements are met.

Required Access and Permissions¶

Common Requirements¶

Active Yappes platform account
API Manager access
Permission to create and manage Gateway Policies
At least one API created under My APIs

API Level¶

A target endpoint must be available
On the endpoint Custom Plugin tab, create and edit are disabled when the API is published

Subscription Level¶

API must be published
An active subscription must be available on the Manage Subscriptions page

Custom Plugin is not restricted by endpoint content type. It can be attached to REST and SOAP endpoints.

System Requirements¶

Supported web browser: Chrome, Edge, or Firefox

Go Plugin Configuration¶

Custom Plugin is configured in the Custom Plugins section. Select Context to load a default Go template, then edit Plugin code in the code editor.

Context Options¶

UI Label	Config Value	Stored Policy Type	Handle Signature
On Request	`on_request`	`custom-request-plugin`	`func Handle(ctx *RequestContext) error`
On Response	`on_response`	`custom-response-plugin`	`func Handle(ctx *ResponseContext) error`

Default On Request Template¶

func Handle(ctx *RequestContext) error {

  //Custom plugin request logic here

 return nil
}

Default On Response Template¶

func Handle(ctx *ResponseContext) error {

  //Custom plugin response logic here

 return nil
}

Info

Do not modify or remove the Handle function. You can add your code inside it or create additional functions outside it.

Validation Rules¶

Check	Where Enforced	Description
Context required	UI	On Request or On Response must be selected
Plugin code required	UI	Editor must not be empty
Balanced brackets and closed strings/comments	UI	Basic Go structural checks in the editor
Forbidden keywords	Server	Code must not use `os`, `system`, `exec`, `syscall`, or `file`
Balanced `{}`	Server	Curly braces must balance
Handle function present	Server	Must match the selected context signature
return nil	Server	Handle body must end with `return nil`
Non-empty Handle body	Server	Handle body cannot be empty

Note

Click the Expand icon to open the editor in full-screen mode for easier editing.
If server validation fails, the platform returns a code validation error and lists the issues to fix.

Custom error and message

For error scenarios, you can override the default HTTP status code, error code, and message. See Custom Error and Message.

Step-by-Step Implementation¶

Method 1: Creating Custom Plugin from the Endpoint Tab¶

Step 1: Navigate to API Manager¶

Click on Manage APIs in the main dashboard.
Select My APIs from the submenu.

Step 2: Open Your API and Select an Endpoint¶

For a new API, follow onboarding steps and open endpoint details.
For an existing API, select it from My APIs and click the target endpoint.

Step 3: Open Custom Plugin Tab¶

Click the Custom Plugin tab on the endpoint details panel.
Click Custom Plugin to create a new policy, or Edit / View on an existing attached policy.

Step 4: Enter Policy Details¶

Enter a descriptive Policy name (e.g. AddGatewayHeaderOnRequest).
Add a Description (max 500 characters).
Select API and endpoint fields are read-only.

Step 5: Select Context and Configure Plugin Code¶

Select Context — On Request or On Response.
Edit Plugin code in the editor. Refer to Go Plugin Configuration for template and validation details.

Step 6: Create the Policy¶

Review the configuration.
Click Create policy (or Save when editing).
Expected Result: The policy is attached to the endpoint.

Info

Each endpoint can have one On request and one On response custom plugin policy attached.

The Custom Plugin create button is disabled when the API is published.

Method 2: Creating Custom Plugin from Gateway Policies Page¶

Step 1: Navigate to Gateway Policies¶

Locate Gateway Control → Gateway Policies in the main navigation menu.

Step 2: Configure Policy Settings¶

Click Create Policy.
Select the appropriate Control Level based on where the policy is required:
API Level — Applies Custom Plugin to a specific API endpoint at creation.
Subscription Level — Creates a reusable policy for attachment to consumer subscription endpoints.
In Policy Type, select Custom Plugin.

For general policy creation guidance, see Creating a policy (w/edit and delete).

Step 3: Define Policy Details¶

Enter Policy Name and Description.

Step 4: Select API and Endpoint (API Level Only)¶

If Control Level is set to API Level:
Select the target API and Source endpoint (or Operation for SOAP APIs).
If Control Level is set to Subscription Level:
No API or endpoint selection is required.

Step 5: Select Context and Configure Plugin Code¶

Select Context — On Request or On Response.
Edit Plugin code in the editor. Refer to Go Plugin Configuration for template and validation details.

Info

At Subscription Level, both On Request and On Response are available during policy creation.

Step 6: Create the Policy¶

Review all settings.
Click Create Policy.

Success

The Custom Plugin policy is successfully created.

Attaching Custom Plugin Policy to Subscriptions¶

Use this flow when you created a policy with Control Level set to Subscription Level in Gateway Policies.

Step 1: Navigate to Manage Subscriptions¶

From the main menu, click Manage Subscriptions.
The Manage Subscriptions page displays a list of all API subscriptions.
Locate the subscription where you want to apply the Custom Plugin policy.

Step 2: Open the Policy Attachment Dialog¶

Click Attach or Detach for the relevant subscription.
The policy attachment dialog opens.

Step 3: Select Endpoint Level¶

In the Attach Policy tab, select Endpoint Level.
Custom Plugin policies do not appear when API Level is selected. The platform shows: "Custom Plugin, JSON, XML and Regex Threat Protections are not listed and cannot be attached at API level."

Step 4: Select Endpoints¶

Select one or more endpoints from the endpoint list.
Custom Plugin is not filtered by content type — any REST endpoint in the subscription can be selected.
After selecting endpoints, proceed to the policy selection step.

For general attach and detach steps, see Manage Subscriptions — Attach/Detach Gateway Policies.

Step 5: Select and Attach the Policy¶

In Select Policy to Attach, choose your subscription-level Custom Plugin policy.
Click Save Changes to apply the policy to the selected endpoints.

Note

Only one policy of the same type can be attached to a subscription at a time. Detach the existing policy before attaching a replacement.
Each endpoint supports at most one On request and one On response Custom Plugin policy.

Understanding the Interface¶

Component	Description
Policy Name	Identifies the Custom Plugin policy
Description	Documents the policy purpose
Context	On Request or On Response — when the Go code runs
Plugin code	Code editor for Go plugin source
Control Level	API Level (single endpoint at creation) or Subscription Level (attach via Manage Subscriptions)

Control Level Summary¶

Control Level	API/Endpoint at Creation	Attach Path
API Level	Required	Endpoint tab or Gateway Policies (auto-attached to selected endpoint)
Subscription Level	Not required	Manage Subscriptions → Endpoint Level

Configuration and Settings¶

Required Configuration Fields¶

Field	Requirement	Description
Policy Name	Mandatory	Min 3 characters; must start with a letter
Description	Optional	Max 500 characters
Control Level	Mandatory	API Level or Subscription Level
API Selection	Mandatory at API Level	Target API; not required at Subscription Level
Endpoint Selection	Mandatory at API Level	Specific endpoint for enforcement; not required at Subscription Level
Context	Mandatory	On Request or On Response
Plugin code	Mandatory	Valid Go plugin with required Handle function

Info

Each endpoint supports at most one On request and one On response Custom Plugin policy.

Best Practices for Configuration¶

Best Practice	Benefit
Keep the Handle function signature unchanged	Ensures the plugin passes validation and runs correctly
End the Handle body with `return nil`	Required by server validation
Avoid forbidden system-level keywords	Prevents save failures from security checks
Use separate On request and On response policies when logic differs	Clearer control per execution phase
Test plugins in non-production before rollout	Reduces risk of blocking legitimate traffic
Prefer built-in policies when they fit	Simpler to maintain than custom Go code

What Happens If Plugin Validation Fails¶

If Custom Plugin validation fails:

The policy is not saved until code issues are fixed
The UI shows validation errors from the editor or from the server response
If a duplicate policy exists for the same endpoint context, the platform blocks creation with a policy-exists error
Fix the listed issues and submit again

Verification and Testing¶

After configuring Custom Plugin:

Send a request through the endpoint and confirm expected gateway behavior.
Verify On Request plugins run before the backend is called.
Verify On Response plugins run on the response path.
Confirm separate On request and On response policies apply when both are configured.
For subscription-level policies, confirm attachment on the intended endpoints only.

Troubleshooting¶

Issue	Possible Cause	Resolution
Custom Plugin tab create button disabled	API is published	Create or edit from Gateway Policies, or use an unpublished API on the endpoint tab
Cannot create second policy	On request or On response slot already filled	Edit the existing policy or choose the other context
Save fails with code validation error	Forbidden keyword, missing Handle, or invalid return	Fix issues listed in the error message
Editor shows syntax issues	Unbalanced brackets or unclosed strings	Fix structural errors highlighted in the editor
Policy not listed in Manage Subscriptions	API Level selected in attach dialog	Switch to Endpoint Level
Duplicate policy error	Same context already attached to endpoint	Detach or edit the existing policy

Impact of Policy Changes¶

Plugin code changes take effect on the next request through the gateway.
Errors in updated code can block traffic until the plugin is fixed or detached.
Replacing a plugin on a live endpoint can change request or response behavior immediately.
Always test updates in non-production before deploying to production.

Frequently Asked Questions¶

How many Custom Plugin policies can I attach per endpoint?
One On request and one On response policy per endpoint.

Is Custom Plugin available at subscription level?
Yes. Create the policy with Control Level set to Subscription Level in Gateway Policies, then attach it via Manage Subscriptions at Endpoint Level. See Attaching Custom Plugin Policy to Subscriptions.

Can I attach Custom Plugin at API Level in Manage Subscriptions?
No. Custom Plugin policies can only be attached at Endpoint Level in Manage Subscriptions. They do not appear in the policy list when API Level is selected.

Can I create or edit a plugin from the endpoint tab after the API is published?
No. On the endpoint Custom Plugin tab, create and edit are disabled when the API is published. Use Gateway Policies to manage existing policies.

Does Custom Plugin depend on endpoint content type?
No. Unlike JSON or XML Threat Protection, Custom Plugin is not restricted by content type.

What is the difference between Custom Plugin and Transformation?
Transformation Policy modifies request or response payloads using configured transformation rules. Custom Plugin runs Go code you write in the Plugin code editor.

Pro Tip

Custom Plugin in Yappes runs Go code at the API Gateway during On Request or On Response. Start with the default template, keep the Handle function intact, end with return nil, and test in non-production before attaching to live subscription endpoints.