Regel

Vermeiden Sie zu brechen. öffentlich API Verträge.
Änderungen an öffentlichen API Endpunkten die würde brechen
bestehende Kunden Anfragen sind brechen Änderungen.
Denken Sie an an die API Vertrag als a Versprechen - ändern
es nach Kunden abhängen auf es bricht ihre Code.

Unterstützte Sprachen: PHP, Java, C#, Python, JavaScript, TypeScript

Einleitung

Öffentliche APIs sind Verträge zwischen Ihrem Dienst und seinen Konsumenten. Sobald Clients vom Anforderungsformat, der Antwortstruktur oder dem Verhalten eines Endpunkts abhängen, führt eine Änderung dazu, dass ihr Code nicht mehr funktioniert. Breaking Changes zwingen alle Clients zu einer gleichzeitigen Aktualisierung, was oft unmöglich ist, wenn Sie die Clients nicht kontrollieren. Mobile Apps können nicht zwangsaktualisiert werden, Drittanbieter-Integrationen benötigen Migrationszeit, und Legacy-Systeme werden möglicherweise nie aktualisiert.

Warum es wichtig ist

Kundenbeeinträchtigung und Vertrauen: Breaking API Changes führen zu sofortigen Fehlern in produktiven Client-Anwendungen. Nutzer erleben Fehler, Datenverlust oder komplette Serviceausfälle. Dies schädigt das Vertrauen zwischen API-Anbietern und -Konsumenten und verletzt den impliziten Vertrag, dass stabile APIs stabil bleiben.

Koordinationskosten: Die Koordination von Breaking Changes über mehrere Client-Teams hinweg ist teuer und langsam. Jedes Team benötigt Zeit, um Code zu aktualisieren, Änderungen zu testen und zu deployen. Bei öffentlichen APIs mit unbekannten Clients (mobile Apps, Drittanbieter-Integrationen) ist eine Koordination unmöglich.

Versionsproliferation: Schlecht verwaltete Breaking Changes führen dazu, dass mehrere API-Versionen gleichzeitig gepflegt werden müssen. Jede Version erfordert separate Codepfade, Tests, Dokumentationen und Bugfixes, was den Wartungsaufwand exponentiell erhöht.

Code-Beispiele

❌ Nicht konform:

// Version 1: Original API
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({ id: user.id, name: user.name });
});

// Version 2: Breaking change - renamed field
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({
        id: user.id,
        fullName: user.name  // Breaking: 'name' renamed to 'fullName'
    });
});

Warum es falsch ist: Das Umbenennen von name in fullName führt dazu, dass alle bestehenden Clients, die das Feld name erwarten, nicht mehr funktionieren. Client-Code, der auf response.name zugreift, erhält undefined, was zu Fehlern führt. Diese Änderung zwingt alle Clients, gleichzeitig zu aktualisieren oder fehlzuschlagen.

✅ Konform:

// Version 2: Additive change - keeps old field, adds new
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({
        id: user.id,
        name: user.name,           // Keep for backward compatibility
        fullName: user.name        // Add new field (deprecated 'name')
    });
});

// Or use API versioning
app.get('/api/v2/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({ id: user.id, fullName: user.name });
});

Warum dies wichtig ist: Das Alte beibehalten Name Das Feld wahrt die Abwärtskompatibilität und fügt hinzu vollständiger Name für neue Kunden. Alternativ kann ein neuer versionierter Endpunkt erstellt werden (/api/v2/) ermöglicht Breaking Changes, ohne bestehende Clients zu beeinträchtigen, die noch /api/v1/.

Fazit

APIs durch additive Änderungen weiterentwickeln: neue Felder, neue Endpunkte und optionale Parameter hinzufügen. Wenn Breaking Changes unvermeidlich sind, API-Versionierung nutzen, um alte und neue Versionen gleichzeitig zu betreiben. Alte Felder mit klaren Zeitplänen und Migrationsleitfäden als veraltet kennzeichnen, bevor sie entfernt werden.