Never Introduce Breaking API Changes

Never Introduce Breaking API Changes

Impact: CRITICAL

Once an API endpoint is public, it must remain stable. Breaking changes destroy developer trust and create integration nightmares for our users.

Strategies for avoiding breaking changes:

• Always add new fields as optional
• Use API versioning when you must change existing behavior
• Deprecate old endpoints gracefully with clear migration paths
• Maintain backward compatibility for at least two major versions

Incorrect (breaking change):

// v1 - Original response
interface BookingResponse {
  id: number;
  startTime: string; // ISO string
}

// v1 - Breaking change: renamed field
interface BookingResponse {
  id: number;
  start: string; // Renamed from startTime - BREAKS CLIENTS
}

Correct (non-breaking evolution):

// v1 - Original response
interface BookingResponse {
  id: number;
  startTime: string;
}

// v1 - Non-breaking: add new field, keep old one
interface BookingResponse {
  id: number;
  startTime: string; // Keep for backwards compatibility
  start: string; // New preferred field
}

When you must make breaking changes:

• Create a new API version using date-specific versioning in API v2
• Run both versions simultaneously during transition
• Provide automated migration tools when possible
• Give users ample time to migrate (minimum 6 months for public APIs)
• Document exactly what changed and why

Reference: Cal.com Engineering Blog