Developer Portal
Çağla Cabaoğlu Gallery API Versioning & Deprecation Policy
This page states how the Çağla Cabaoğlu Gallery REST API and MCP server are versioned, and exactly how a change is announced before it lands. Agents can integrate against these guarantees.
1. Versioning
- The version lives in the URL path: /api/v1/… The current stable version is v1.
- Every /api/v1 response carries an X-API-Version: v1 header.
- Backwards-compatible additions (new fields, new endpoints) ship inside v1 and do not change the version number. Clients must ignore unknown fields.
- Breaking changes ship under a new path version (/api/v2). v1 keeps working for at least the notice period below.
- The MCP server negotiates protocol versions through the MCP-Protocol-Version header and answers 400 for an unsupported version.
2. How a deprecation is announced
- The endpoint starts returning a Deprecation: true header (RFC 9745).
- The response links to this policy and to the replacement: Link: </docs/deprecation-policy>; rel="deprecation" and Link: </api/v1>; rel="successor-version".
- Once a removal date is set, an RFC 8594 Sunset header carrying that HTTP-date is added at least 6 months before removal.
- The same signal is published in openapi.json (deprecated: true plus x-sunset) and in the /.well-known/api-catalog linkset.
- After removal the endpoint answers 410 Gone and links to its successor.
3. Current status
| Surface | Status | Sunset | Successor |
|---|---|---|---|
| /api/v1/* | Stable | — | — |
| /api/mcp | Stable | — | — |
| /api/llm/* | Deprecated | Not yet announced | /api/v1/* |
Deprecated endpoints keep working. No endpoint is removed before a Sunset date has been announced.
4. Watching for changes
Agents should inspect the Deprecation and Sunset headers on every response. For advance notice on production integrations, write to us: contactgallery@caglacabaoglu.com.