Praxiswissen · Praxisleitfaden

API-Versionwechsel unter GxP: Mapping und Fehler prüfen

Die Schnittstelle antwortet weiterhin erfolgreich. Trotzdem interpretiert das Zielsystem einen neuen Status oder eine geänderte Einheit falsch. Bei einem API-Versionwechsel muss deshalb der fachliche Datenvertrag geprüft werden – nicht nur die Erreichbarkeit des Endpunkts.

Daniel Herrmann
Compliance-Experte für Life Sciences
Fachlicher Stand: 7 Minuten Lesezeit
Inhaltsverzeichnis

Das Wichtigste vorab

Was muss bei einem API-Versionwechsel im GxP-Betrieb geprüft werden?

Bewerten Sie Änderungen an Datenstruktur, Bedeutung, Einheiten, Statusregeln, Authentifizierung und Fehlerbehandlung gegen den vorgesehenen Prozess. Prüfen Sie kritische Mappings mit bekannten Soll-Ergebnissen und betrachten Sie den tatsächlichen Zielzustand. Ergänzen Sie fehlende, doppelte, verspätete und abgewiesene Nachrichten. Eine technische Erfolgsantwort beweist keine vollständige fachliche Verarbeitung.

Den fachlichen Datenvertrag erfassen

Ein API-Vertrag umfasst mehr als Feldnamen. Dokumentieren Sie, was eine Nachricht fachlich bedeutet, welches System führend ist und wann ein Vorgang als abgeschlossen gilt. Beschreiben Sie Objektidentität, Datentypen, Einheit, erlaubte Zustände und notwendige Beziehungen. Ein Feld „status“ kann beispielsweise Prüfstatus, Übertragungsstatus oder Geschäftsfreigabe meinen. Diese Bedeutungen dürfen beim Versionswechsel nicht unbemerkt vermischt werden.

Legen Sie die Systemgrenze fest. Dazu können Quellanwendung, API-Gateway, Integrationsdienst, Mapping und Zielprozess gehören. Ein Test nur des Gateways deckt die Verarbeitung im Ziel nicht ab. Erfassen Sie die tatsächlich verwendeten API-Versionen und kundenspezifischen Transformationen. Die Bezeichnung „kompatibles Update“ des Anbieters ist ein Eingang für die Bewertung, aber keine automatische Bestätigung, dass jeder eigene Prozess unverändert richtig arbeitet.

Quellen: [1] [2]

Änderungen nach Bedeutung statt nur nach Schema beurteilen

Vergleichen Sie alte und neue Definitionen. Neue Pflichtfelder, andere Datentypen und entfernte Werte sind offensichtliche Kandidaten. Ebenso relevant können unveränderte Feldnamen mit anderer Bedeutung sein: Menge jetzt in einer anderen Einheit, Zeitstempel mit neuem Bezug oder ein zusätzlicher Statuswert. Ein formal valides JSON kann fachlich falsch interpretiert werden. Der Relevanzreview braucht deshalb Wissen über den tatsächlichen Anwenderprozess.

Bewerten Sie auch scheinbar additive Änderungen. Ein neues optionales Feld kann eine bestehende Verarbeitung unbeeinflusst lassen; ein neuer Enumwert kann dagegen eine unvollständige Fallunterscheidung treffen. Eine andere Sortierung oder Seitengröße kann die Vollständigkeit einer Abfrage verändern. Dokumentieren Sie, welche Änderungen betroffen sind und warum weitere Nachweise entfallen dürfen. Eine reine Liste geänderter Endpunkte beantwortet diese Auswirkungsfrage nicht.

Quellen: [1]

Konstruiertes Beispiel: eine Einheit ändert sich

Im Beispiel überträgt Version 1 einen Ergebniswert von 9,8 mit der Einheit mg. Version 2 liefert denselben fachlichen Wert als 0,0098 g. Das Ziel muss nach der festgelegten Regel weiterhin 9,8 mg bewerten. Ein Parser, der nur den Zahlenwert übernimmt, erzeugt ein scheinbar plausibles, aber falsches Ergebnis. Das unabhängig berechnete Soll wird vor dem Test dokumentiert.

Ergänzend führt die neue Version den Status „pending_review“ ein. Im Beispiel darf dieser Zustand nicht als freigegeben gelten. Prüfen Sie die konkrete Zuordnung sowie einen unbekannten zukünftigen Wert. Die geeignete Reaktion wird aus dem Prozess abgeleitet, etwa Zurückstellung mit verantwortlicher Klärung. Die folgende Matrix ist eine eigene Arbeitshilfe. Sie behauptet keine universelle API-Konvention und keine allgemein verpflichtende technische Behandlung jedes unbekannten Felds.

Eigene Arbeitshilfe: Konstruiertes Beispiel: eine Einheit ändert sich
ÄnderungFachliches RisikoGezielter Nachweis
mg zu gFalsche GrößenordnungUnabhängige Einheitenumrechnung
Neuer StatusUnberechtigte WeiterverarbeitungErlaubte und unbekannte Werte
Feld wird optionalUnvollständige AufzeichnungFehlender und leerer Wert
Neue SeitengrößeUnvollständige PopulationMehrere Seiten mit bekanntem Bestand
Anderer ZeitbezugFalsche EreignisreihenfolgeQuelle und Zielzeitpunkt vergleichen
Neue FehlerantwortUngeklärter TeilzustandAbbruch und kontrollierter Wiederanlauf

Quellen: [1]

Syntax, Mapping und Zielzustand getrennt prüfen

Ein Schematest prüft Struktur und zulässige Typen. Ein Mappingtest prüft die fachliche Zuordnung. Ein Prozessnachweis prüft, ob der richtige Zielzustand entstanden ist. Diese Ebenen ergänzen sich. Ein Test, der nur einen erfolgreichen HTTP-Status erwartet, kann eine fehlerhafte Speicherung übersehen. Prüfen Sie deshalb relevante Zielobjekte und Beziehungen mit geeigneten autorisierten Zugängen.

Verwenden Sie bekannte Referenznachrichten und unabhängige Sollwerte. Prüfen Sie Zahlen, Datumsformate, führende Nullen, Sonderzeichen und leere Werte dort, wo sie den Prozess beeinflussen. Halten Sie Quell- und Zielidentität zusammengehörig fest. Eine manuelle Korrektur während des Tests wird dokumentiert und darf nicht als unverändertes Schnittstellenergebnis erscheinen. Wenn ein Testwerkzeug selbst Daten umformt, muss dessen Rolle im Nachweis verstanden sein.

Quellen: [1] [2]

Wiederholung, Reihenfolge und Teilverarbeitung prüfen

Netzunterbrechungen können einen unklaren Zustand erzeugen: Der Client erhält keine Antwort, obwohl das Ziel bereits verarbeitet hat. Definieren Sie, wie Wiederholung erkannt und behandelt wird. Ein erneutes Senden darf keine unbemerkte Doppelbuchung verursachen. Das konkrete Verfahren hängt vom API-Vertrag und eigenen Design ab. Eine technische Request-ID allein beweist nicht, dass das Ziel fachlich idempotent arbeitet.

Prüfen Sie verspätete und vertauschte Nachrichten. Ein älterer Status darf einen neueren nicht unkontrolliert überschreiben, wenn die Prozessregel dies ausschließt. Bei Stapelverarbeitung können einzelne Datensätze erfolgreich und andere abgewiesen sein. Legen Sie fest, wie diese Teilzustände sichtbar werden und weiter bearbeitet werden. Ein globales „Job beendet“ reicht nicht als Nachweis, dass jede relevante Aufzeichnung vollständig und richtig übernommen wurde.

Quellen: [1]

Zugriff und Protokollierung beim Versionswechsel bewerten

Eine neue Version kann andere Berechtigungen, technische Identitäten oder Authentifizierungswege verwenden. Prüfen Sie den tatsächlich benötigten Zugriff und den Entzug alter Berechtigungen nach dem kontrollierten Übergang. Testen Sie eine unberechtigte Aktion und die Verfügbarkeit notwendiger Funktionen für die vorgesehene Rolle. Ein erfolgreich authentifizierter technischer Benutzer ist nicht automatisch für jeden Datenzugriff autorisiert.

Bestimmen Sie den benötigten Nachweis für technische Verarbeitung und fachliche Änderung. Schnittstellenlogs, Geschäftsbelege und Audit-Trails können unterschiedliche Informationen liefern. Eine Nachricht mit vertraulichem Inhalt darf nicht ohne passende Schutz- und Aufbewahrungsentscheidung beliebig vervielfältigt werden. Protokollieren Sie so, dass Fehler und betroffene Objekte rekonstruierbar sind. Der genaue Umfang richtet sich nach Prozess, Risiko und benötigter historischer Aussage.

Quellen: [1] [2]

Übergang und Rückfall vorab planen

Definieren Sie, ob alte und neue Version zeitweise parallel verwendet werden. Prüfen Sie, welche Daten in welchem Format verarbeitet werden und wie offene Vorgänge behandelt werden. Ein Rückfall kann schwierig sein, wenn die neue Version bereits Daten erzeugt hat, die die alte nicht versteht. Bewerten Sie diese Grenze vor dem Wechsel. Ein technisch verfügbarer alter Endpunkt ist noch kein vollständiger fachlicher Rückfallplan.

Planen Sie den Cut-off, die letzte alte Nachricht, die erste neue Nachricht und den Abgleich danach. Kontrollieren Sie die relevante Population und bekannte Sonderfälle. Nach dem Übergang werden alte Verbindungen und Zugriffe im freigegebenen Umfang beendet. Vermeiden Sie einen ungeklärten Parallelbetrieb, der denselben Vorgang über zwei Wege verarbeitet. Die erforderlichen Produktivkontrollen werden vorab festgelegt und ergänzen die Tests in geeigneter Umgebung.

Quellen: [1]

Regression und Betriebsverantwortung erhalten

Der Abschluss verbindet Änderung, betroffene Anforderungen, geprüfte Nachrichtentypen, Ergebnisse und Betriebsmaßnahmen. Benennen Sie Grenzen ausdrücklich. Eine geprüfte Ergebnisübertragung belegt nicht automatisch alle Stammdaten- oder Rückrufnachrichten derselben API. Verwenden Sie eine kontrollierte Sammlung kritischer Referenzfälle, die nach relevanten Änderungen erneut genutzt werden kann. Sie muss fachlich gepflegt werden, nicht nur technisch ausführbar bleiben.

Legen Sie Verantwortliche für API-Vertrag, Mapping, Fehlerbearbeitung und fachlichen Abgleich fest. Neue Statuswerte, Datenfelder oder Deprecation-Hinweise brauchen einen geregelten Eingang in die Änderungsbewertung. Die eigentliche Qualität liegt im dauerhaft nachvollziehbaren Zusammenhang von Quelle und Ziel. Ein grüner Erreichbarkeitstest und eine lange Logdatei können diesen Nachweis unterstützen, ersetzen ihn aber nicht.

Quellen: [1]

Häufige Fragen zu API-Änderung und Validierung

Muss eine neue API-Version immer vollständig revalidiert werden?

Bewerten Sie die konkrete Änderung und ihre Auswirkungen. Betroffene Datenwege, Funktionen und Risiken benötigen geeignete Nachweise. Stabil gebliebene Bereiche können begründet anders behandelt werden. Ein pauschaler Volltest ist nicht immer sinnvoll; ein Testverzicht allein wegen behaupteter Kompatibilität ist ebenfalls nicht ausreichend.

Reicht HTTP 200 als erfolgreicher Validierungstest?

Nein. Eine technische Erfolgsantwort kann je nach Vertrag nur Empfang oder einen Verarbeitungsschritt bestätigen. Prüfen Sie die benötigte fachliche Speicherung und den richtigen Zielzustand. Bei asynchronen Abläufen werden spätere Verarbeitung und Fehlerbearbeitung zusätzlich betrachtet. Die Akzeptanzkriterien müssen die tatsächliche Prozessaussage abdecken.

Können neue optionale Felder bestehende Prozesse beeinflussen?

Ja, abhängig von Implementierung und Bedeutung. Auch zusätzliche Statuswerte, andere Sortierung oder Seitengrößen können bestehende Annahmen treffen. Bewerten Sie den Datenvertrag und die eigenen Verarbeitungsschritte. Nicht jede additive Änderung ist kritisch, aber ihre Nichtbetroffenheit sollte nachvollziehbar begründet sein.

Was ist bei Wiederholungen nach einem Timeout zu prüfen?

Ob der erste Versuch bereits fachlich verarbeitet wurde und wie eine erneute Nachricht behandelt wird. Prüfen Sie Doppelverarbeitung, Identitätszuordnung und erkennbaren Zielzustand. Das geeignete Verfahren hängt vom konkreten API-Design ab. Blindes Wiederholen kann bei teilweiser Verarbeitung zusätzliche Fehler erzeugen.

Gehören Berechtigungen zur API-Änderungsprüfung?

Ja, soweit sie durch die Änderung betroffen sind oder die benötigte Funktion beeinflussen. Prüfen Sie technische Identität, erlaubten Umfang und abgewiesene Aktionen. Der kontrollierte Entzug alter Zugriffe gehört zum Übergang. Authentifizierung allein belegt keine passende Autorisierung für sämtliche Daten und Funktionen.

Wann ist ein Rückfall wirklich möglich?

Wenn der alte Weg die erforderlichen Daten und offenen Vorgänge weiterhin korrekt verarbeiten kann und die Rückkehr geprüft beziehungsweise ausreichend begründet ist. Neue Datenformate können dies einschränken. Definieren Sie Auslöser, Verantwortliche und Abgleich. Die bloße Existenz eines alten Endpunkts reicht nicht aus.

Quellen & fachlicher Stand

Stand: 14. Oktober 2026. Regulatorische Einordnung und Herstellerfunktionen sind getrennt belegt. Beispiele, Testmatrizen und Vorlagen sind eigene Arbeitshilfen; sie werden für den tatsächlichen Einsatzzweck angepasst.

  1. Europäische Kommission: EU-GMP Annex 11, Computerised Systems (2011)
  2. PIC/S: PI 041-1, Good Practices for Data Management and Integrity (2021)

Zuletzt fachlich geprüft am 14.10.2026.

Daniel Herrmann, Daniel Herrmann Consulting

Daniel Herrmann Consulting

Wie wir Sie dabei unterstützen

Daniel Herrmann Consulting verbindet die fachliche Bewertung mit der Arbeit am konkreten System. Im Erstgespräch klären wir Ihren Einsatzzweck, vorhandene Nachweise und den nächsten sinnvollen Schritt.

  • IT-GxP-Consulting →

    Anforderungen, Tests und Umsetzung für Ihren konkreten Systemprozess zusammenführen.

Ihr Vorhaben besprechenEinblicke in unsere Projektarbeit →