A standardized way for registries to provide experimental or community-driven features without committing them to the core API specification.
The core generic registry API intentionally stays minimal to ensure stability and broad adoption. Extensions provide a path for:
- Experimentation: Try new features without core API changes
- Community innovation: Anyone can implement custom extensions
- Gradual adoption: Popular extensions may inform future core API features
- Avoiding breaking changes: Failed experiments can be deprecated without API versioning churn
Extensions live under the /v0.1/x/ prefix:
/v0.1/x/<namespace>/<extension>[/<path>]
Components:
<namespace>: Reverse domain ownership (e.g.,com.example,io.github.username)<extension>: Extension name (lowercase, hyphens for word separation)<path>: Extension-specific path structure (optional)
Examples:
/v0.1/x/com.example/search?q=database
/v0.1/x/com.example/stats
/v0.1/x/io.github.username/custom-feature
Where possible:
- Follow standard REST conventions, return simple JSON responses, and avoid special headers
- For list endpoints, use cursor-based pagination matching the core API
- Extensions requiring authentication SHOULD follow the Registry Authorization Specification
- Build open-source implementations in a composable way on top of the core APIs (e.g. as opposed to via custom database integration)
Registries implementing extensions SHOULD namespace extensions properly to avoid conflicts.
Clients consuming extensions MUST gracefully handle missing extensions.
A simple server stats extension:
GET /v0.1/x/com.example/stats{
"totalServers": 1234,
"totalVersions": 5678,
"recentPublishes": 42
}- Extension discovery: A potential
/v0.1/xendpoint to list available extensions - Extension metadata: Standardized metadata format for extension capabilities
- Defining common extensions: Like semantic conventions from OpenTelemetry, develop common extensions that registries can adopt (possibly under an experimental namespace)