Principle:OpenHands OpenHands Integration Router Mounting
| Knowledge Sources | |
|---|---|
| Domains | Server_Architecture, SaaS_Infrastructure |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Dynamically mounting integration-specific API routers based on enabled providers allows the server to expose only the endpoints relevant to the configured third-party integrations.
Description
The Integration Router Mounting principle addresses the challenge of supporting multiple third-party service integrations (GitHub, GitLab, Jira, and others) without requiring all of them to be active in every deployment. Each integration provides its own API router containing endpoints for OAuth callbacks, webhook handlers, and integration-specific operations. During server assembly, the application checks environment variables or configuration flags to determine which integrations are enabled and mounts only those routers onto the FastAPI application. This ensures that the server exposes a minimal and relevant API surface, avoids initializing unused integration clients, and prevents confusion from endpoints that cannot function without their required credentials.
Usage
Apply this principle when the server supports multiple optional integrations that each provide their own set of API endpoints. It is particularly relevant in SaaS platforms where different deployments or tenants may have different integrations enabled. The conditional mounting pattern should be used whenever the presence of an integration depends on external configuration such as API keys, client IDs, or feature flags.
Theoretical Basis
The plugin architecture pattern provides the foundation for conditional router mounting. In this pattern, each integration is treated as a self-contained plugin that registers its routes, dependencies, and handlers independently. The server acts as a host that discovers available plugins (by checking configuration flags) and activates only those that meet their prerequisites. This approach follows the open-closed principle: the server is open for extension (new integrations can be added as new router modules) but closed for modification (existing code does not need to change when a new integration is introduced). The conditional inclusion based on environment variables ensures that the server's API surface accurately reflects its actual capabilities, preventing clients from discovering endpoints that would fail at runtime due to missing credentials.