API versioning policy
Semver strict · URL-based versioning · 6 reglas claras · deprecation 12 meses notice mandatory · 8-step deprecation timeline · 6 migration support resources · sunset history transparent. NO breaking changes silenciosos · NO sunset <12m warning.
6 versioning rules
Deprecation timeline · 8-step process (12 meses notice)
No client surprises. Cada deprecation sigue mismo flow predictible. 12 meses min entre announcement y sunset.
- T-0 · Decision: Deprecate v1 endpoint identified · ADR documented WHY + WHEN replacement available + impact assessment
- T+30d · Announcement: Public deprecation notice via /changelog + email registered API users + Twitter status + docs banner ANTES de Sunset announcement
- T+90d · Sunset announcement: Specific sunset date 12m future committed · migration guide published with code examples old vs new
- T+120d · Migration assistance: Office hours support migrations · 1:1 customer success calls Enterprise clients · changelog updates
- T+180d · Half-way reminder: 6 months remaining notice · usage analytics shared with high-volume clients · personalized migration path
- T+270d · 90-day warning: 3 months remaining · escalating notifications · status page degraded labeled v1
- T+330d · 30-day warning: Final notice · clients NOT migrated identified · personalized outreach · last chance migration help
- T+365d · Sunset: v1 endpoint returns 410 Gone status · responseBody includes migration guide URL + support contact · audit log every call attempted to deprecated
6 migration support resources
Sunset history · transparente
| Version | Deprecated | Sunset | Impact | Lessons |
|---|---|---|---|---|
| v0.x (pre-stable) | 2026-01-15 | Active beta only · NEVER promoted stable · sunset trivial | 0 clientes externos (pre-revenue · solo demo internal) | Pre-stable APIs NO se commit públicamente · solo experimental |
| v1 (current stable) | Not yet deprecated | TBD · earliest 2027 · 12m+ notice | TBD · plan when v2 announced | v1 long-term support committed · migrations slow rollout planned |
| v2 (future planned) | N/A · futuro | N/A · futuro | Pre-tracción · scope limited | v2 si emerge customer demand · NO speculative |
Esta política pública se compromete ANTES de tener clientes externos API · NO post-hoc. Razón: cliente Enterprise procurement security/integration team valida API stability commitment · ver written policy es señal seriedad.
Caveats honest: 12m deprecation notice asume clients integrados · si pre-tracción NO hay clients integrados · políticas commitment para futuro · serán probadas con primer cliente API integration real.
¿Tu engineering team necesita API integration guide?
Para clientes Enterprise · OpenAPI 3.1 spec completa · Postman collection · code samples 4 idiomas · webhook signatures + retry logic detalle disponibles bajo NDA Enterprise.