Align registry API with toolhive-registry-server v0.1 surface
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 2.2k
- Forks
- 300
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 184
Description
Summary
Make toolhive's registry API a mirror of the v0.1 surface that stacklok/toolhive-registry-server exposes. This:
- Drops the legacy-shaped
/api/v1beta/registry/...endpoints. - Refactors the
/registry/{registryName}/v0.1/servershandler to consumetoolhive-core/registry/typesdirectly (same patternpkg/api/v1/registry_v01_skills.goalready uses — noconvertersimport). - Adds the per-version sub-resources that registry-server exposes but toolhive doesn't yet (servers and skills both).
Phase 1 (parse-side internals + error-code cleanup) is stacklok/toolhive#5278.
Reference: registry-server's v0.1 surface
GET /registry/{registryName}/v0.1/servers
GET /registry/{registryName}/v0.1/servers/{serverName}/versions
GET /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}
GET /registry/{registryName}/v0.1/x/dev.toolhive/skills
GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}
GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions
GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version}
Source of truth: stacklok/toolhive-registry-server docs/thv-registry-api/swagger.yaml.
Scope
Remove:
pkg/api/v1/registry.gov1beta servers handlers (/api/v1beta/registry/{name}/servers,/{serverName}) and the legacy[]*registry.ImageMetadata/[]*registry.RemoteServerMetadataresponse structs.pkg/api/v1/registry_v01_servers.go/versions/latestshortcut (replace with the version paths below).
Refactor:
pkg/api/v1/registry_v01_servers.go— drop thetoolhive-core/registry/convertersimport; consume upstream types directly, mirroringpkg/api/v1/registry_v01_skills.go.- Internal registry provider chain — return upstream-shaped types instead of
ImageMetadata/RemoteServerMetadata.
Add (to match registry-server surface):
GET /registry/{registryName}/v0.1/servers/{serverName}/versionsGET /registry/{registryName}/v0.1/servers/{serverName}/versions/{version}GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versionsGET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version}
Coordination
- FE counterpart: studio currently consumes
/api/v1beta/registry/{name}/serversand modelsRegistryItemaroundRegistryImageMetadata/RegistryRemoteServerMetadata. It needs to migrate to the new v0.1 surface — tracked separately.
Blocks
- stacklok/toolhive-core#106 (legacy Go types and
registry/converters/removal)
Acceptance criteria
-
/api/v1beta/registry/{name}/serversand/{serverName}removed. - No toolhive code imports
toolhive-core/registry/converters. - No toolhive code references
registry.ImageMetadata/registry.RemoteServerMetadata. - toolhive's v0.1 endpoint set matches registry-server's swagger.
- OpenAPI spec regenerated;
task docsgreen.
References
- Pattern reference (already aligned):
pkg/api/v1/registry_v01_skills.go - Surface reference:
stacklok/toolhive-registry-serverdocs/thv-registry-api/swagger.yaml - Phase 1: stacklok/toolhive#5278
- Landed: stacklok/toolhive-catalog#1215, stacklok/toolhive-core#105, stacklok/toolhive#5273
- Downstream blocker: stacklok/toolhive-core#106
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with pkg/api/v1/registry_v01_servers.go and the matching pattern in pkg/api/v1/registry_v01_skills.go, then compare the routes with toolhive-registry-server's docs/thv-registry-api/swagger.yaml. Trace the internal registry provider chain and the legacy handlers in pkg/api/v1/registry.go. Done means the v0.1 endpoints match the reference, legacy types and converter imports are gone, and regenerated OpenAPI passes task docs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100