1a7cd97099<!-- 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>
123 lines
No EOL
3.7 KiB
Markdown
123 lines
No EOL
3.7 KiB
Markdown
# 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](https://github.com/modelcontextprotocol/registry/issues/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:**
|
|
```json
|
|
{
|
|
"_meta": {
|
|
"io.modelcontextprotocol.registry/official": {
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"published_at": "2024-01-01T00:00:00Z",
|
|
"is_latest": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**New Structure:**
|
|
```json
|
|
{
|
|
"_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. |