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

Einführung

Öffentliche APIs sind Verträge zwischen Ihrem Dienst und seinen Nutzern. Wenn Clients vom Anfrageformat, der Antwortstruktur oder dem Verhalten eines Endpunkts abhängig sind, führt eine Änderung zu einem Bruch in ihrem Code. Diese Änderungen zwingen alle Clients zur gleichzeitigen Aktualisierung, was oft unmöglich ist, wenn Sie die Clients nicht kontrollieren. Mobile Anwendungen können nicht zwangsaktualisiert werden, Integrationen von Drittanbietern benötigen Zeit für die Migration, und ältere Systeme werden möglicherweise nie aktualisiert.

Warum das wichtig ist

Störung der Kunden und Vertrauen: Brüchige API-Änderungen führen zu sofortigen Ausfällen bei Client-Anwendungen in der Produktion. Die Benutzer erleben Fehler, Datenverluste oder komplette Serviceausfälle. Dies schadet dem Vertrauen zwischen API-Anbietern und Kunden und verletzt den impliziten Vertrag, dass stabile APIs stabil bleiben.

Koordinierungskosten: Die Koordinierung von Änderungen zwischen mehreren Kundenteams ist teuer und langsam. Jedes Team braucht Zeit, um den Code zu aktualisieren, Änderungen zu testen und bereitzustellen. Bei öffentlichen APIs mit unbekannten Kunden (mobile Anwendungen, Integrationen von Drittanbietern) ist eine Koordinierung unmöglich.

Wucherung der Versionen: Schlecht verwaltete Änderungen führen zur gleichzeitigen Pflege mehrerer API-Versionen. Jede Version erfordert separate Codepfade, Tests, Dokumentationen und Fehlerkorrekturen, wodurch sich der Wartungsaufwand exponentiell vervielfacht.

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 das falsch ist: Die Umbenennung von name in fullName unterbricht alle bestehenden Clients, die das Feld name erwarten. Client-Code, der auf response.name zugreift, erhält undefinierte Werte, was zu Fehlern führt. Diese Änderung zwingt alle Clients zur gleichzeitigen Aktualisierung oder zum Fehlschlag.

✅ 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 das wichtig ist: Beibehaltung der alten Name behält die Abwärtskompatibilität bei und fügt gleichzeitig vollständiger Name für neue Kunden. Alternativ dazu kann ein neuer versionierter Endpunkt (/api/v2/) erlaubt es, Änderungen vorzunehmen, ohne dass bestehende Clients, die noch /api/v1/.

Schlussfolgerung

Entwickeln Sie APIs durch additive Änderungen weiter: Fügen Sie neue Felder, neue Endpunkte und optionale Parameter hinzu. Wenn einschneidende Änderungen unvermeidlich sind, verwenden Sie die API-Versionierung, um alte und neue Versionen gleichzeitig auszuführen. Veralten Sie alte Felder mit klaren Zeitplänen und Migrationsleitfäden, bevor Sie sie entfernen.