Änderungen aus Clientsicht bewerten
Die Tabelle ist eine Prüfhilfe ohne allgemeine Garantie. Zusätzliche Felder können strikte Leser stören, neue Aufzählungswerte vollständige Fallunterscheidungen brechen. Clients, Bibliotheken und Annahmen inventarisieren.
| Änderung | Zu prüfendes Risiko | Benötigter Nachweis |
|---|---|---|
| Feld entfernen oder umbenennen | Leser findet es nicht mehr | Ausdrückliche Migration und Clienttests. |
| Optionales Feld hinzufügen | Strikter Leser oder Namenskonflikt | Bestehende Verbraucher testen. |
| Neuer Aufzählungswert in Antworten | Unvollständige Fallunterscheidung | Umgang mit unbekannten Werten. |
| Vorgabewert ändern | Anderes fachliches Ergebnis | Fälle ohne ausdrücklichen Wert vergleichen. |
Koexistenz organisieren
- Alte und neue Strukturen, Vorgaben, Fehler, Seitennavigation und Berechtigungen beschreiben. Vertragsprüfungen mit repräsentativen Clientszenarien ausführen.
- Versionsauswahl ausdrücklich festlegen. Dienstversion und OpenAPI-Dokumentversion unterscheiden; Caches und Gateways prüfen.
- Zeitplan, Migrationsanleitung und Kontakt veröffentlichen. Tatsächliche Nutzung angemessen messen und datenkompatible Rückkehr vorbereiten.
Abkündigung vom Abschalten trennen
Deprecation kennzeichnet abgekündigte Ressourcen; Sunset kann ihre erwartete Nichtverfügbarkeit ankündigen. Header migrieren keine Clients. Vor Abschaltung verbliebene Nutzer, Pflichten und Wiederherstellung prüfen.
Primärquellen
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Auswirkungen der Versionierung auf den Nutzer
Das Hinzufügen einer Nummer zu einer URL erhält bestehende Clients nicht automatisch. Ein geänderter Typ, erwarteter Wert, ein geändertes Verhalten oder eine geänderte Fehlermeldung können inkompatibel sein, selbst wenn der Pfad gleich bleibt.
- Aktive Clients und deren Nutzung erfassen.
- Ältere Clientversionen mit dem neuen Vertrag testen.
- Einen Koexistenzzeitraum festlegen und die Nutzung vor der Außerbetriebnahme prüfen.
Primärquelle: IETF RFC 9457 — Problem Details for HTTP APIs. Verwandte Methode: den praktischen Leitfaden lesen.
Asynchrone API-Aufgaben
Eine angenommene Anfrage beweist keine abgeschlossene Arbeit.
- Konto, Vorgang und wiederverwendbare Kennung
- Zustand, Zeit, Intervall und Ablauf
- Resultat, Fehler, Abbruch und verbleibende Auswirkungen
- Eine autorisierte Aufgabe und geprüftes Ergebnis nach Unterbrechung
Nachvollziehbarer Abnahmefall
Fiktives Beispiel: Diese Daten beschreiben keine Kunden oder beobachteten Ergebnisse.
Falldaten anzeigen
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Erwartete Entscheidung
Eine Statusantwort 200 bedeutet nicht, dass die Verarbeitung beendet ist. Nach einer Abbruchanforderung zählt nur das bestätigte Ergebnis.
Abbruch zu spät angefordert
Fiktives Beispiel: derselbe Auftrag J-42, Sekunden seit Einreichung. Die Zustandsnamen gehören zu diesem Beispielvertrag; HTTP schreibt sie nicht vor.
| Zeitpunkt | Antwort und Zustand | Belegte Aussage |
|---|---|---|
| +0 s | HTTP 202 · pending | Zur Verarbeitung angenommen; kein Endergebnis bestätigt. |
| +5 s | HTTP 200 · running | Die Statusabfrage war erfolgreich; der Auftrag läuft weiter. |
| +6 s | HTTP 200 · cancel_requested | Stoppanforderung erfasst; Abbruch noch nicht bestätigt. |
| +7 s | HTTP 200 · succeeded | Die Verarbeitung war schneller. Bestätigten Erfolg anzeigen und Auswirkungen prüfen; keinen Abbruch melden. |
Beweist 202 einen späteren Abschluss?
Nein. Es bestätigt die Annahme zur Verarbeitung, nicht das Endergebnis. Den Vorgangsstatus prüfen.
Primärquelle: MDN — 202 Accepted. Verwandte Methode: den praktischen Leitfaden lesen.
Softwareupdates: einen Signiererwechsel prüfen
Prüfen, ob ein signiertes Artefakt weiterhin zum freigegebenen Hersteller, Build und Release gehört.
- Erfasse vor der Paketprüfung zugelassenen Hersteller, Schlüssel oder Zertifikatsidentität, Aussteller und Buildprozess. Binde Erwartungen an die Software und einen bereits vertrauenswürdigen Bestätigungskanal. Das Artefakt darf nicht allein seine eigene Annahmerichtlinie bestimmen.
- Vergleiche den Digest der erhaltenen Datei mit dem Gegenstand der Attestierung. Prüfe die Signatur gegen vorgesehene Vertrauensanker, danach Identität, Builder und Parameter. Eine gültige Signatur einer anderen Identität erfüllt die Dienstrichtlinie nicht.
- Teste angekündigte Rotation, unerwarteten Aussteller, fehlende Signatur und abweichende Datei. Halte das Artefakt zurück, wenn die neue Identität unbestätigt ist. Dokumentiere Freigabe und Rückweg; eine Signatur beweist keine Schwachstellenfreiheit.
Nachvollziehbarer Abnahmefall
Fiktives Beispiel: Diese Daten beschreiben keine Kunden oder beobachteten Ergebnisse.
Falldaten anzeigen
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Erwartete Entscheidung
Fiktives Beispiel: Digest und Signatur stimmen, doch der Signierer entspricht nicht der freigegebenen Identität. Installation bleibt bis zur unabhängigen Bestätigung der Änderung ausgesetzt.
Primärquelle: SLSA v1.2 — Verifying artifacts. Verwandte Methode: den praktischen Leitfaden lesen.
API-Abkündigung und Stilllegung
Ausführliche Hinweise stehen in dieser Ausgabe auf Englisch zur Verfügung.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23