How API Gateways Implement Custom Plugins

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.