Developer Policies

API Versioning & Deprecation Policy

Lifecycle commitments, semantic versioning, and deprecation timeline for alpyalay.org REST API and MCP services.

Current: API v1.0.0

180-Day Sunset Window

1. Versioning Strategy

All REST API endpoints are explicitly versioned in the URI path (`/api/v1/`). Any breaking modifications require a new major version route (`/api/v2/`), ensuring existing integrations continue operating without disruption.

2. Deprecation Notice Protocol

When an endpoint or schema is scheduled for retirement, we commit to a minimum 180-day (6 months) deprecation notice window. During this phase, all affected HTTP responses emit standard RFC headers:

Deprecation: @<unix-timestamp>
Sunset: <HTTP-date>
Link: <https://alpyalay.org/developers/deprecation>; rel="deprecation"

3. Error Formats & Grace Period

Sunset endpoints return machine-readable RFC 9457 `application/problem+json` errors directing agents to the migration guide.

Back to Developer Portal