Implement Handlers and Capabilities
Handlers define what your agent can do. Capabilities tell API Control Plane which of those operations to call. You must implement both for any functionality you want to expose.
Prerequisites
GatewayandGatewayConfigurationclasses implemented (see Implement Gateway and GatewayConfiguration)
Key concepts
| Term | Description |
|---|---|
| Handler | Interface containing the methods for a specific area of functionality, such as API discovery or plan deployment. |
| HandlerFactory | Interface that creates instances of a Handler. |
| Capability | A named, versioned flag that tells API Control Plane which Handler methods your agent supports. |
CapabilityFactory | Interface your agent implements to report its supported capabilities and versions. |
DiagnosticsService | Interface your agent must implement so API Control Plane can display the gateway connection status. |
Implement Handlers and HandlerFactories
For each area of functionality you want to support:
- Implement the Handler interface (for example,
ApiDiscoveryHandler) with the required methods. - Implement the corresponding HandlerFactory interface (for example,
ApiDiscoveryHandlerFactory). - Return a new instance of your HandlerFactory from the appropriate
GatewayManager::getXFactorymethod. For details, see Implement GatewayManager.
If you implement a Handler method but do not report the corresponding capability, API Control Plane will not call that method. If you report a capability but do not implement the required methods, an UnsupportedOperationException is thrown when that operation is attempted.
Implement CapabilityFactory
Implement CapabilityFactory to report which capabilities your agent supports and at which versions. Report only the capabilities whose required methods you have fully implemented.
Implement DiagnosticsService
Implement DiagnosticsService and DiagnosticsServiceFactory so API Control Plane can display the connection status of your gateway. Without this implementation, the gateway status will not appear correctly in the UI.
Supported capabilities
| Capability | Required implementation | Version to report |
|---|---|---|
ApiDiscovery | ApiDiscoveryHandler::discoverApis | 1 |
ComponentDiscovery | ComponentDiscoveryHandler::discoverPlansAndApplications | 1 |
ComponentDeployment | PlanHandler::deploy and undeploy; SubscriptionHandler::deploy and undeploy; ApplicationHandler::deploy and undeploy | 3 |
CustomFieldDiscovery | CustomFieldDiscoveryHandler::discoverCustomFields | 1 |
ApiMetrics | MetricsHandler::get for requests of type API | 1 |
ApplicationMetrics | MetricsHandler::get for requests of type APPLICATION | 1 |
RawMetrics | MetricsHandler::fetch for requests of type API and/or APPLICATION | 1 |
ApiImport | ApiImportExportHandler::import; ApiImportExportHandler::getBundleFileName | 1 |
ApiExport | ApiImportExportHandler::export; ApiImportExportHandler::getBundleFileName | 1 |
AccessPermissionRegeneration | SubscriptionHandler::regenerateAccessPermission | 1 |
ApiProducts | ComponentDiscoveryHandler::discoverPlansAndApplications with API Products support; PlanHandler::deployForProduct | 1 |
OpenProxySpecDeployment | OpenProxySpecHandler::deploy | 2 |
OAuthConfig | ApplicationHandler::deploy with OAuth configuration support | 1 |
EnvironmentDiscovery | EnvironmentDiscoveryHandler::discover; ApiDiscoveryHandler::discoverApisInEnvironment; ComponentDiscoveryHandler::discoverPlansAndApplicationsInEnvironment | 1 |
Capability behavior notes
RawMetrics: When you report this capability, API Control Plane uses only MetricsHandler::fetch for metrics retrieval. MetricsHandler::get is not called.
ApiProducts: When you report this capability, API Control Plane uses only PlanHandler::deployForProduct for plan deployment. PlanHandler::deploy is not called.
EnvironmentDiscovery: When you report this capability, API Control Plane uses only the discoverXInEnvironment methods. The standard discoverX methods are not called.
OpenProxySpecDeployment: The OpenProxySpecHandler::deployApi method targets an experimental v1.1 of the Open Proxy Specification. You can ignore this method until v1.1 is released.
BuildInfo, ProcessId, GatewayId: These are internal capabilities. Reporting or not reporting them has no effect on agent functionality.
