ab21c7f805
* feat: Cal.diy — community-driven MIT-licensed fork of Cal.com This squashed commit contains all Cal.diy changes applied on top of calcom/cal.com main: - Rebrand Cal.com to Cal.diy across the entire codebase - Remove Enterprise Edition (EE) features, license checks, and AGPL restrictions - Switch license from AGPL-3.0 to MIT - Remove docs/ directory (migrated to Nextra at cal.diy) - Remove dead code: org tests, EE tips, platform nav, premium username, SAML/SSO, etc. - Clean up .env.example for self-hosted Cal.diy - Update Docker image references to calcom/cal.diy - Update README, CONTRIBUTING.md, and issue templates for Cal.diy community fork - Add PR welcome bot for Cal.diy contributors - Fix API v2 breaking changes oasdiff ignore entries - Replace Blacksmith CI runners with default GitHub Actions 3893 files changed, 20789 insertions(+), 411020 deletions(-) Co-Authored-By: benny@cal.com <sldisek783@gmail.com> * refactor: remove org-specific /organizations/:orgId endpoints from API v2 atoms controllers (#1701) Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix: revert Cal.diy Inc to Cal.com, Inc. in license files, copyright notices, and package metadata (#1702) Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * rip out org related comments in api v2 --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
---
|
|
title: Never Introduce Breaking API Changes
|
|
impact: CRITICAL
|
|
impactDescription: Maintains developer trust and prevents integration nightmares
|
|
tags: api, stability, versioning, backwards-compatibility
|
|
---
|
|
|
|
## 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):**
|
|
|
|
```typescript
|
|
// 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):**
|
|
|
|
```typescript
|
|
// 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.diy Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)
|