Skip to content

Commit 1a7cd97

Browse files
rdimitrovrdimitrov
authored
Introduce v0.1 version of the API (#658)
<!-- Provide a brief summary of your changes --> ## Motivation and Context <!-- Why is this change needed? What problem does it solve? --> The following PR adds a new v0.1 API version. The goal is to mark v0.1 as a "freeze" point while keeping v0 as the moving target for new features so integrators can start building on top of something stable(r). Details: * This change is quite simple - we re-register the same handlers twice, once as `v0` and once as `v0.1` * Going forward, we'll keep v0.1 frozen while we add changes either on top of both (non-breaking) or we'll have to branch if breaking changes are necessary * We all acknowledge this is not exactly best-practice, but it gives us a way to gather feedback and allow clients to start integrating with the API without breaking them (**note** this implies a follow up PR that would branch the handlers used in v0.1). * For integrators/clients: please provide your feedback - what works well, what doesn't so we can take this into account going towards GA. ## How Has This Been Tested? <!-- Have you tested this in a real application? Which scenarios were tested? --> ## Breaking Changes <!-- Will users need to update their code or configurations? --> No, this just adds a new API version alongside the existing one. ## Types of changes <!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: --> - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update ## Checklist <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> - [ ] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [ ] My code follows the repository's style guidelines - [ ] New and existing tests pass locally - [ ] I have added appropriate error handling - [ ] I have added or updated documentation as needed ## Additional context <!-- Add any other context, implementation notes, or design decisions --> Fixes: #649 Signed-off-by: Radoslav Dimitrov <[email protected]>
1 parent 69f45c4 commit 1a7cd97

24 files changed

+116
-78
lines changed

‎docs/guides/consuming/use-rest-api.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,20 @@ Integration patterns and best practices for building applications that consume M
44

55
## Key details
66

7-
**Base URL**: `https://registry.modelcontextprotocol.io`
7+
**Base URL**: `https://registry.modelcontextprotocol.io`
88

99
**Authentication**: Not required for read-only access
1010

11-
- **`GET /v0/servers`** - List all servers with pagination
12-
- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
13-
- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
11+
**API Versions**:
12+
- `/v0/` - Development version with latest features (may receive additive changes)
13+
- `/v0.1/` - Stable version (only backward-compatible changes)
14+
15+
**Recommendation**: Use `/v0.1/` for production applications requiring API stability. Both versions currently have identical functionality.
16+
17+
**Core endpoints:**
18+
- **`GET /v0.1/servers`** - List all servers with pagination
19+
- **`GET /v0.1/servers/{serverName}/versions`** - List all versions of a server
20+
- **`GET /v0.1/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
1421

1522
Server names and version strings should be URL-encoded in paths.
1623

‎docs/reference/api/CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,24 @@ Changes to the REST API endpoints and responses.
44

55
## Unreleased
66

7+
### Added
8+
9+
#### API Versioning - v0.1 Introduction
10+
11+
Introduced `/v0.1/` as a stable API version while `/v0/` continues as the development version.
12+
13+
**New version paths:**
14+
- All `/v0/` endpoints are now also available at `/v0.1/`
15+
- Both versions currently share identical behavior
16+
- `/v0/` will continue to evolve with additive changes (new optional fields, new endpoints)
17+
- `/v0.1/` will remain stable with only additive, backward-compatible changes
18+
- Both versions will be maintained until a future v1.0 release
19+
20+
**Migration guidance:**
21+
- Production applications should consider using `/v0.1/` for stability
22+
- Development and testing can continue using `/v0/` for latest features
23+
- No immediate action required - `/v0/` remains fully supported
24+
725
### ⚠️ BREAKING CHANGES
826

927
#### Endpoint Simplification

‎internal/api/handlers/v0/auth/dns.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,14 @@ func (h *DNSAuthHandler) SetResolver(resolver DNSResolver) {
5050
}
5151

5252
// RegisterDNSEndpoint registers the DNS authentication endpoint
53-
func RegisterDNSEndpoint(api huma.API, cfg *config.Config) {
53+
func RegisterDNSEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
5454
handler := NewDNSAuthHandler(cfg)
5555

5656
// DNS authentication endpoint
5757
huma.Register(api, huma.Operation{
58-
OperationID: "exchange-dns-token",
58+
OperationID: "exchange-dns-token" + pathPrefix,
5959
Method: http.MethodPost,
60-
Path: "/v0/auth/dns",
60+
Path: pathPrefix + "/auth/dns",
6161
Summary: "Exchange DNS signature for Registry JWT",
6262
Description: "Authenticate using DNS TXT record public key and signed timestamp",
6363
Tags: []string{"auth"},

‎internal/api/handlers/v0/auth/github_at.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,15 +42,15 @@ func (h *GitHubHandler) SetBaseURL(url string) {
4242
h.baseURL = url
4343
}
4444

45-
// RegisterGitHubATEndpoint registers the GitHub access token authentication endpoint
46-
func RegisterGitHubATEndpoint(api huma.API, cfg *config.Config) {
45+
// RegisterGitHubATEndpoint registers the GitHub access token authentication endpoint with a custom path prefix
46+
func RegisterGitHubATEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
4747
handler := NewGitHubHandler(cfg)
4848

4949
// GitHub token exchange endpoint
5050
huma.Register(api, huma.Operation{
51-
OperationID: "exchange-github-token",
51+
OperationID: "exchange-github-token" + pathPrefix,
5252
Method: http.MethodPost,
53-
Path: "/v0/auth/github-at",
53+
Path: pathPrefix + "/auth/github-at",
5454
Summary: "Exchange GitHub OAuth access token for Registry JWT",
5555
Description: "Exchange a GitHub OAuth access token for a short-lived Registry JWT token",
5656
Tags: []string{"auth"},

‎internal/api/handlers/v0/auth/github_oidc.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -226,14 +226,14 @@ func (h *GitHubOIDCHandler) SetValidator(validator OIDCValidator) {
226226
}
227227

228228
// RegisterGitHubOIDCEndpoint registers the GitHub OIDC authentication endpoint
229-
func RegisterGitHubOIDCEndpoint(api huma.API, cfg *config.Config) {
229+
func RegisterGitHubOIDCEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
230230
handler := NewGitHubOIDCHandler(cfg)
231231

232232
// GitHub OIDC token exchange endpoint
233233
huma.Register(api, huma.Operation{
234-
OperationID: "exchange-github-oidc-token",
234+
OperationID: "exchange-github-oidc-token" + pathPrefix,
235235
Method: http.MethodPost,
236-
Path: "/v0/auth/github-oidc",
236+
Path: pathPrefix + "/auth/github-oidc",
237237
Summary: "Exchange GitHub OIDC token for Registry JWT",
238238
Description: "Exchange a GitHub Actions OIDC token for a short-lived Registry JWT token",
239239
Tags: []string{"auth"},

‎internal/api/handlers/v0/auth/http.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -108,14 +108,14 @@ func (h *HTTPAuthHandler) SetFetcher(fetcher HTTPKeyFetcher) {
108108
}
109109

110110
// RegisterHTTPEndpoint registers the HTTP authentication endpoint
111-
func RegisterHTTPEndpoint(api huma.API, cfg *config.Config) {
111+
func RegisterHTTPEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
112112
handler := NewHTTPAuthHandler(cfg)
113113

114114
// HTTP authentication endpoint
115115
huma.Register(api, huma.Operation{
116-
OperationID: "exchange-http-token",
116+
OperationID: "exchange-http-token" + pathPrefix,
117117
Method: http.MethodPost,
118-
Path: "/v0/auth/http",
118+
Path: pathPrefix + "/auth/http",
119119
Summary: "Exchange HTTP signature for Registry JWT",
120120
Description: "Authenticate using HTTP-hosted public key and signed timestamp",
121121
Tags: []string{"auth"},

‎internal/api/handlers/v0/auth/main.go‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,23 @@ import (
55
"github.com/modelcontextprotocol/registry/internal/config"
66
)
77

8-
// RegisterAuthEndpoints registers all authentication endpoints
9-
func RegisterAuthEndpoints(api huma.API, cfg *config.Config) {
8+
// RegisterAuthEndpoints registers all authentication endpoints with a custom path prefix
9+
func RegisterAuthEndpoints(api huma.API, pathPrefix string, cfg *config.Config) {
1010
// Register GitHub access token authentication endpoint
11-
RegisterGitHubATEndpoint(api, cfg)
11+
RegisterGitHubATEndpoint(api, pathPrefix, cfg)
1212

1313
// Register GitHub OIDC authentication endpoint
14-
RegisterGitHubOIDCEndpoint(api, cfg)
14+
RegisterGitHubOIDCEndpoint(api, pathPrefix, cfg)
1515

1616
// Register configurable OIDC authentication endpoints
17-
RegisterOIDCEndpoints(api, cfg)
17+
RegisterOIDCEndpoints(api, pathPrefix, cfg)
1818

1919
// Register DNS-based authentication endpoint
20-
RegisterDNSEndpoint(api, cfg)
20+
RegisterDNSEndpoint(api, pathPrefix, cfg)
2121

2222
// Register HTTP-based authentication endpoint
23-
RegisterHTTPEndpoint(api, cfg)
23+
RegisterHTTPEndpoint(api, pathPrefix, cfg)
2424

2525
// Register anonymous authentication endpoint
26-
RegisterNoneEndpoint(api, cfg)
26+
RegisterNoneEndpoint(api, pathPrefix, cfg)
2727
}

‎internal/api/handlers/v0/auth/none.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ func NewNoneHandler(cfg *config.Config) *NoneHandler {
2828
// RegisterNoneEndpoint registers the anonymous authentication endpoint
2929
// WARNING: This endpoint is intended for local development and automated tests only.
3030
// It should NOT be enabled in production environments as it bypasses normal authentication.
31-
func RegisterNoneEndpoint(api huma.API, cfg *config.Config) {
31+
func RegisterNoneEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
3232
if !cfg.EnableAnonymousAuth {
3333
return
3434
}
@@ -39,7 +39,7 @@ func RegisterNoneEndpoint(api huma.API, cfg *config.Config) {
3939
huma.Register(api, huma.Operation{
4040
OperationID: "get-anonymous-token",
4141
Method: http.MethodPost,
42-
Path: "/v0/auth/none",
42+
Path: pathPrefix + "/auth/none",
4343
Summary: "Get anonymous Registry JWT (Development/Testing Only)",
4444
Description: "Get a short-lived Registry JWT token for publishing and editing servers in the io.modelcontextprotocol.anonymous/* namespace. This endpoint is intended for local development and automated testing only.",
4545
Tags: []string{"auth"},

‎internal/api/handlers/v0/auth/oidc.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ func (h *OIDCHandler) SetValidator(validator GenericOIDCValidator) {
145145
}
146146

147147
// RegisterOIDCEndpoints registers all OIDC authentication endpoints
148-
func RegisterOIDCEndpoints(api huma.API, cfg *config.Config) {
148+
func RegisterOIDCEndpoints(api huma.API, pathPrefix string, cfg *config.Config) {
149149
if !cfg.OIDCEnabled {
150150
return // Skip registration if OIDC is not enabled
151151
}
@@ -154,9 +154,9 @@ func RegisterOIDCEndpoints(api huma.API, cfg *config.Config) {
154154

155155
// Direct token exchange endpoint
156156
huma.Register(api, huma.Operation{
157-
OperationID: "exchange-oidc-token",
157+
OperationID: "exchange-oidc-token" + pathPrefix,
158158
Method: http.MethodPost,
159-
Path: "/v0/auth/oidc",
159+
Path: pathPrefix + "/auth/oidc",
160160
Summary: "Exchange OIDC ID token for Registry JWT",
161161
Description: "Exchange an OIDC ID token from any configured provider for a short-lived Registry JWT token",
162162
Tags: []string{"auth"},

‎internal/api/handlers/v0/edit.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@ type EditServerInput struct {
2525
Body apiv0.ServerJSON `body:""`
2626
}
2727

28-
// RegisterEditEndpoints registers the edit endpoint
29-
func RegisterEditEndpoints(api huma.API, registry service.RegistryService, cfg *config.Config) {
28+
// RegisterEditEndpoints registers the edit endpoint with a custom path prefix
29+
func RegisterEditEndpoints(api huma.API, pathPrefix string, registry service.RegistryService, cfg *config.Config) {
3030
jwtManager := auth.NewJWTManager(cfg)
3131

3232
// Edit server endpoint
3333
huma.Register(api, huma.Operation{
34-
OperationID: "edit-server",
34+
OperationID: "edit-server" + pathPrefix,
3535
Method: http.MethodPut,
36-
Path: "/v0/servers/{serverName}/versions/{version}",
36+
Path: pathPrefix + "/servers/{serverName}/versions/{version}",
3737
Summary: "Edit MCP server",
3838
Description: "Update a specific version of an existing MCP server (admin only).",
3939
Tags: []string{"admin"},

0 commit comments

Comments
 (0)