modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
registry/docs/reference/api/CHANGELOG.md
Radoslav Dimitrov 1a7cd97099
 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 <radoslav@stacklok.com>
2025-10-14 11:04:48 +03:00

3.7 KiB
Raw Blame History

Registry API Changelog

Changes to the REST API endpoints and responses.

Unreleased

Added

API Versioning - v0.1 Introduction

Introduced /v0.1/ as a stable API version while /v0/ continues as the development version.

New version paths:

  • All /v0/ endpoints are now also available at /v0.1/
  • Both versions currently share identical behavior
  • /v0/ will continue to evolve with additive changes (new optional fields, new endpoints)
  • /v0.1/ will remain stable with only additive, backward-compatible changes
  • Both versions will be maintained until a future v1.0 release

Migration guidance:

  • Production applications should consider using /v0.1/ for stability
  • Development and testing can continue using /v0/ for latest features
  • No immediate action required - /v0/ remains fully supported

⚠️ BREAKING CHANGES

Endpoint Simplification

Removed redundant endpoint to simplify API surface and reduce implementation burden for subregistries.

Removed endpoints:

  • GET /v0/servers/{serverName} - Use GET /v0/servers/{serverName}/versions/latest instead

2025-09-29

⚠️ BREAKING CHANGES

API Endpoint Restructuring

API endpoints updated to use server names instead of server IDs for better usability.

Changed endpoints:

  • GET /v0/servers/{server_id} → GET /v0/servers/{serverName}
  • GET /v0/servers/{server_id}/versions → GET /v0/servers/{serverName}/versions

New endpoints:

  • GET /v0/servers/{serverName}/versions/{version} - Get specific server version
  • PUT /v0/servers/{serverName}/versions/{version} - Edit server version (admin only)

Response format changes:

  • Introduced ServerResponse schema separating server data from registry metadata
  • Moved status field from server data to _meta.io.modelcontextprotocol.registry/official
  • Removed io.modelcontextprotocol.registry/official metadata from ServerDetail schema

Changed

  • OpenAPI spec version: 2025-09-16 → 2025-09-29

2025-09-16

⚠️ BREAKING CHANGES

Server ID Endpoints (#396)

API endpoints updated for consistent server identification across versions.

Problem: Each server version had a unique ID, preventing version history tracking and server renaming.

Solution: Introduced consistent server identification across versions.

Changed endpoints:

  • GET /v0/servers/{id} → GET /v0/servers/{server_id}

New endpoints:

  • GET /v0/servers/{server_id}/versions - List all versions of a server
  • GET /v0/servers/{server_id}?version=1.0.0 - Get specific version

Changed response metadata:

  • _meta.*.id → _meta.*.serverId
  • Added: _meta.*.versionId

Migration Examples

Old Structure:

{
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "published_at": "2024-01-01T00:00:00Z",
      "is_latest": true
    }
  }
}

New Structure:

{
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "serverId": "550e8400-e29b-41d4-a716-446655440000",
      "versionId": "773f9b2e-1a47-4c8d-b5e6-2f8d9c4a7b3e",
      "published_at": "2024-01-01T00:00:00Z",
      "is_latest": true
    }
  }
}

Migration Checklist for API Consumers

  • Update API endpoint URLs from /v0/servers/{id} to /v0/servers/{server_id}
  • Update code reading registry metadata from id to serverId/versionId
  • Add support for new /v0/servers/{server_id}/versions endpoint if needed
  • Update JSON parsing to expect camelCase field names
  • Test with new API responses

Changed

  • OpenAPI spec version: 2025-07-09 → 2025-09-16

2025-07-09

Initial release of the Registry API.