How API Gateways Implement Custom Plugins
API7.ai
April 25, 2025
Introduction
API gateways serve as a central point for managing API traffic, offering features such as authentication, rate limiting, observability, and traffic shaping. However, out-of-the-box features may not cover all use cases. This is where custom plugins come into play.
Custom plugins empower developers to extend API gateway functionality according to specific business or technical needs. This article explores the architecture, development, deployment, and best practices of custom plugins in API gateways.
Why Custom Plugins Are Important
Use Cases
- Business Logic Enforcement: Inject specific rules, policies, or metadata into the request flow.
- Custom Authentication: Integrate with in-house auth systems or token formats.
- Data Transformation: Modify request/response headers or payload formats.
- Monitoring: Emit custom metrics or logs for observability.
Benefits
- Greater flexibility
- Enhanced reusability
- Modular and maintainable architecture
Plugin Architecture in API Gateways
Most API gateways support a modular architecture for plugins. These plugins are executed as part of the request lifecycle and typically support various phases:
- Rewrite phase: Modify the request before routing.
- Access phase: Perform authentication or rate limiting.
- Balancer phase: Handle upstream selection.
- Header filter phase: Modify headers before sending the response.
- Body filter phase: Modify the response body.
- Log phase: Emit logs or metrics post-request.
Plugin Lifecycle
sequenceDiagram participant Client participant Gateway participant Plugin participant Upstream Client->>Gateway: Send API Request Gateway->>Plugin: Execute Rewrite Phase Gateway->>Plugin: Execute Access Phase Gateway->>Upstream: Forward Request Upstream-->>Gateway: Response Gateway->>Plugin: Execute Header Filter Gateway->>Plugin: Execute Body Filter Gateway->>Plugin: Execute Log Phase Gateway-->>Client: Return Response
Plugin Development Models
Lua Plugins (e.g., Apache APISIX, Kong)
- Pros: Fast startup, low memory, native integration
- Cons: Lua learning curve
- Example: Apache APISIX
-- sample.lua function _M.access(conf, ctx) core.log.info("Custom plugin executing") if ctx.var.uri == "/blocked" then return 403, "Forbidden" end end
Go Plugins (e.g., APISIX via Wasm or RPC)
- Pros: Strong typing, rich ecosystem
- Cons: More complex build pipeline
- Example:
func Access(ctx context.Context, request *apisix.Request) (*apisix.Response, error) { if request.Path == "/custom" { return apisix.Response{Status: 200, Body: "Handled by Go plugin"}, nil } return nil, nil }
JavaScript/Node.js Plugins (e.g., KrakenD, Express Gateway)
- Pros: Familiar language, fast iteration
- Cons: Higher resource usage
Wasm Plugins (e.g., Envoy, APISIX)
- Pros: Language agnostic, sandboxed
- Cons: Experimental in some gateways
Plugin Deployment Models
In-Process Execution
Plugins are executed within the gateway process for low latency. Common in Lua or embedded JavaScript engines.
External Execution (via RPC)
Plugins run as external services communicating via gRPC, HTTP, or Unix domain socket.
- Pros: Isolation, multi-language support
- Cons: Slightly higher latency, deployment complexity
RPC Plugin Execution Model
sequenceDiagram participant Client participant APISIX participant PluginRunner participant Java|Go|Node|Python Client->>APISIX: Send HTTP/gRPC/MQTT request APISIX->>APISIX: Apply global rules (e.g. limit rate, security) APISIX->>APISIX: Match route Note over APISIX: Pre-Request Phase APISIX->>PluginRunner: ext-plugin-pre-req (RPC) PluginRunner->>Java|Go|Node|Python: run validator / rewrite-header / rewrite-args Java|Go|Node|Python-->>PluginRunner: return result PluginRunner-->>APISIX: return pre-processing result APISIX->>APISIX: Apply route-specific plugins Note over APISIX: Post-Request Phase APISIX->>PluginRunner: ext-plugin-post-req (RPC) PluginRunner->>Java|Go|Node|Python: run rewrite-status / rewrite-header / rewrite-body Java|Go|Node|Python-->>PluginRunner: return result PluginRunner-->>APISIX: return post-processing result APISIX->>Client: Return final response
Best Practices for Plugin Development
Design Guidelines
- Keep plugins stateless
- Use configuration for logic branching
- Limit heavy computation in the request path
Testing
- Unit test core logic independently
- Use gateway's plugin test framework or Docker-based test harnesses
Versioning & Compatibility
- Pin plugin versions to avoid breaking changes
- Follow semantic versioning and document changelogs
Security
- Validate inputs strictly
- Avoid arbitrary code execution
- Leverage gateway's security context (e.g., sandboxing)
Conclusion
Custom plugins are essential for tailoring API gateway behavior to specific requirements. Whether you need to enforce business logic, extend observability, or integrate with custom auth systems, writing and deploying plugins can unlock powerful capabilities.
By understanding plugin lifecycles, development models, and deployment options, engineers can safely extend their gateway's functionality while maintaining performance and reliability.
FAQ
1. What language should I use to write a custom plugin?
It depends on your gateway. Lua is popular for APISIX and Kong, while Envoy supports Wasm and KrakenD supports Go/JS.
2. Are custom plugins portable across gateways?
Not usually. Each gateway has its own plugin API and lifecycle management.
3. Can plugins affect performance?
Yes. Poorly written plugins can slow down request handling. Always test and monitor performance.
4. How do I debug custom plugins?
Use built-in logging, structured outputs, and local testing frameworks provided by the gateway.
Next Steps
Stay tuned for our upcoming column on the API gateway Guide, where you'll find the latest updates and insights!
Eager to deepen your knowledge about API gateways? Follow our Linkedin for valuable insights delivered straight to your inbox!
If you have any questions or need further assistance, feel free to contact API7 Experts.