PrestaShop 9.2 Admin-API-Änderungen: Versanddienstleister- und Antwortverträge
Ein API-Client kann scheitern, obwohl sich die aufgerufene URL nicht geändert hat. Ein Pflichtfeld kann genauer beschrieben werden, eine fehlende Entität kann nun einen ausdrücklichen Fehler erzeugen oder ein Abfrageergebnis kann einen anderen internen Zuordnungspfad durchlaufen. Das sind Vertragsfragen, die gezielte Tests verdienen.
PrestaShop 9.2 RC1 enthält Arbeiten an der Versanddienstleister-Domäne und der API sowie eine Änderung für listenliefernde CQRS-Abfragen. Dieser Artikel untersucht diese konkreten Änderungen und ihre Integrationsfolgen. Er setzt Vertrautheit mit der Admin API voraus und wiederholt weder Authentifizierungs- noch API-Platform-Grundlagen.
Die Prüfung entspricht dem Stand vom 26. September 2026. RC1 bleibt ein Bewertungsziel; die folgenden Beispiele beschreiben Vertragstestmethoden, keine überprüften Antworten eines laufenden Shops in diesem Projekt.
Enthält eine API-Antwort individuelle Felder, beziehen Sie den Modulintegrationsablauf für Extra Properties in die Vertragsprüfung ein, statt anzunehmen, dass jedes registrierte Feld bereitgestellt werden sollte.
Versanddienstleister-Unterstützung umfasst Core und Ressourcenmodul
Die Versanddienstleister-Arbeiten im Core sind mit Ressourcenarbeiten in ps_apiresources verbunden. Der integrierte Core-PR benennt Korrekturen für den ordnungsgemäßen Betrieb der Versanddienstleister-Ressourcen, darunter skalare Abfrageargumente, moderner Shop-Kontext und eine Prüfung auf fehlende Produkte. Änderung der Versanddienstleister-Domäne und API Nr. 42022.
Für Client-Entwickler folgt daraus unmittelbar, beide Versionen zu dokumentieren. „Core 9.2“ beschreibt das in einem bestimmten Shop installierte Ressourcenverzeichnis nicht vollständig. Prüfen Sie vor der Übernahme eines Vorgangs die generierte Dokumentation dieser Installation und bestätigen Sie seine Verfügbarkeit mit einer autorisierten Sandbox-Anfrage.
Kopieren Sie keine vorgeschlagene Route aus einer Problemdiskussion und nehmen Sie nicht an, dass sie ausgeliefert wurde. Eine Core-Änderung kann eine separat paketierte Ressource unterstützen und ein Review-Kommentar eine frühere Iteration beschreiben. Verwenden Sie das installierte Schema und die passende Quellcoderevision gemeinsam.
Erstellen Sie den kleinsten hilfreichen Testdatensatz für Versanddienstleister: einen bekannten Versanddienstleister, ein dem betreffenden Shop zugeordnetes Produkt und eine bewusst nicht vorhandene Produktkennung. Halten Sie Versandregeln zunächst einfach, damit ein Domänenvalidierungsfehler nicht mit einer Zulässigkeitsregel verwechselt wird.
Generierte Anfrageschemata sind Teil des Vertrags
Derselbe Versanddienstleister-PR behandelt aus Befehlen abgeleitete Anfragetext-Dokumentation: ausgelassene Eigenschaften, Pflichtstatus und von Ressourcen bereitgestellten Schemakontext. Er ergänzt außerdem die Behandlung von Vorgangsstandardwerten vor Zuordnung und Validierung. Schema- und Standardwertdetails.
Das ist für generierte Clients wichtig. Ein veraltetes Schema kann einen Client dazu verleiten, erforderliche Informationen auszulassen oder verschachtelte Werte falsch darzustellen. Eine Client-Neugenerierung ohne Prüfung der Unterschiede kann dann Änderungen weit über den übernommenen Vorgang hinaus einführen.
Erfassen Sie Basisschema und Kandidatenschema aus den jeweiligen Installationen. Prüfen Sie Pflichtfelder, Null-Zulässigkeit, Strukturen von Array-Elementen und Standardwerte. Bestätigen Sie, welche Unterschiede Vorgänge betreffen, die Ihr Client tatsächlich aufruft.
Ein dokumentierter Standardwert ist kein Grund, unterschiedslos null zu senden. Ausgelassene, null und ausdrückliche Werte können verschiedene Bedeutungen haben. Testen Sie jeden Zustand, den Ihre Anwendung erzeugen kann, und dokumentieren Sie das resultierende Verhalten.
Vergleichen Sie bei einem Schreibvorgang die gespeicherte Entität mit der Anfrage, nicht nur das HTTP-Ergebnis. Eine Anfrage kann akzeptiert werden, während ein Standardwert ein Ergebnis erzeugt, das von der Geschäftserwartung des Clients abweicht.
Fehlende Entitäten und Shop-Umfang benötigen Negativfälle
Ein aussagekräftiger Vertragstest enthält eine Kennung, die im Testdatensatz nicht existieren kann. Die Versanddienstleister-Arbeiten sorgen dafür, dass das Setzen von Referenzen für ein unbekanntes Produkt ausdrücklich scheitert, statt stillschweigend nichts zu tun. Verhalten bei fehlenden Produkten.
Ihr Client sollte dies als fehlgeschlagenen Geschäftsvorgang behandeln. Eine erfolgreiche Synchronisierung zu protokollieren, nur weil eine Transportanfrage abgeschlossen wurde, würde den Unterschied verbergen.
Testen Sie auch eine reale Entität in einem ungeeigneten Shop-Kontext. Eine gültige globale Kennung beweist nicht, dass ein Vorgang in jedem Shop gültig ist. Verwenden Sie den dokumentierten Umfangsmechanismus des installierten Vorgangs und prüfen Sie die resultierende Zuordnung oder den Wert im vorgesehenen Shop.
Vermeiden Sie es, bei fehlendem Kontext stillschweigend den Standardshop einzusetzen. Erfordert Ihre Anwendung einen Einzelshop-Vorgang, validieren Sie diese Anforderung vor dem Absenden. Eine clientseitige Vorbedingung kann einen vagen Serverfehler verhindern und den vorgesehenen Umfang in Protokollen verdeutlichen.
Setzen Sie ein leeres Zulässigkeitsergebnis nicht mit einem Fehler gleich. Eine gültige Anfrage kann zu Recht keine zulässigen Versanddienstleister finden. Halten Sie dieses Ergebnis getrennt von verweigertem Zugriff, einem ungültigen Produkt oder einer Serverausnahme.
Listenabfrage-Zuordnung bedeutet keine neue Hülle für jede Antwort
Eine separate Änderung in Version 9.2 verpackt einfache Listenergebnisse von CQRS-Vorgängen außerhalb von Collections unter einem internen Zuordnungsschlüssel _queryResult. Assoziative Ergebnisse behalten ihr bisheriges Zuordnungsverhalten. Der PR erklärt, dass dieser Schlüssel die Zuweisung eines Listenergebnisses zu einer Ressourceneigenschaft ermöglicht. Listenergebnis-Zuordnung Nr. 42011.
Entscheidend ist der Unterschied zwischen der internen Zuordnungseingabe und der öffentlichen Antwortdarstellung. Sagen Sie nicht jedem API-Client, dass er eine Eigenschaft auf oberster Ebene namens _queryResult erwarten soll. Ressourcenmapping und Serialisierung bestimmen die bereitgestellte Struktur.
Prüfen Sie bei einer Erweiterung mit einer geeigneten Ressource eine gefüllte und eine leere Liste. Das leere Ergebnis ist wichtig, weil Code es häufig als fehlende Daten oder unerwarteten Typ behandelt. Der Client sollte in beiden Fällen die dokumentierte Darstellung erhalten.
Wenn Sie Vertragsmomentaufnahmen pflegen, vergleichen Sie die geparste Struktur statt unwichtiger Formatierung oder Eigenschaftsreihenfolge. Eine hilfreiche Prüfung kontrolliert den erwarteten Feldtyp und die Werte. Ein Rohtextvergleich kann an harmlosen Serialisierungsänderungen scheitern und zugleich einen semantischen Unterschied an anderer Stelle übersehen.
Diese Änderung ist eine gezielte Zuordnungsverbesserung. Sie ist kein Beleg dafür, dass alle Collection-Vorgänge oder alle bestehenden Clients neu geschrieben werden müssen.
Die Bereitstellung von Extra Properties ergänzt eine Datenvertragsdimension
Übernimmt eine Integration eine neu registrierte Eigenschaft, behandeln Sie sie als Teil des Geschäftsvertrags. Definieren Sie Verantwortlichen, Typ, Bedeutung eines leeren Werts und Shop- oder Sprachumfang, bevor ein anderes System sie schreiben darf.
Leiten Sie die externe Nutzlast nicht aus der Verwaltungsbeschriftung eines Feldes ab. Prüfen Sie das installierte Ressourcenschema und eine bestätigte Beispielantwort. Bewahren Sie den Modulnamensraum und die genaue unterstützte Darstellung im Client-Mapping.
Ein Feld kann in einem Verwaltungsformular verfügbar sein, während eine Integration nicht für seine Nutzung konfiguriert oder autorisiert ist. Umgekehrt kann ein bereitgestellter Wert die Berechtigungen seiner übergeordneten Entität erben, statt eine separate Feldrichtlinie zu haben. Prüfen Sie dieses Verhalten in der aktuellen Funktionsdokumentation und Installation.
Ergänzen Sie für eine neue Eigenschaft vollständige Zyklusfälle: einen gültigen Wert schreiben, zurücklesen, falls unterstützt löschen, einen ungültigen Wert ablehnen und bestätigen, dass ein zweiter Shop unverändert bleibt. Halten Sie diese Fälle von gewöhnlichen Produktfeldern getrennt, damit Fehler die neue Erweiterungsoberfläche benennen.
Wenn Sie Extra Properties nicht nutzen, erweitern Sie die Schreibnutzlast Ihres Clients nicht allein deshalb, weil der Kandidat sie bereitstellen kann. Übernehmen Sie nur die Felder, die Ihr Geschäftsvertrag benötigt.
Einen kleinen Vertragsvergleichsablauf erstellen
Die folgende Python-Hilfe vergleicht das Pfad- und Methodenverzeichnis zweier lokal gespeicherter OpenAPI-JSON-Dateien. Sie ruft keinen Shop ab, authentifiziert sich nicht und validiert kein Vorgangsverhalten:
import json
from pathlib import Path
METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}
def operations(filename):
document = json.loads(Path(filename).read_text(encoding="utf-8"))
return {
(method.upper(), path)
for path, item in document.get("paths", {}).items()
for method in item
if method.lower() in METHODS
}
before = operations("baseline-openapi.json")
after = operations("candidate-openapi.json")
print("Added:", sorted(after - before))
print("Removed:", sorted(before - after))
Verwenden Sie Dateinamen für die tatsächlich gespeicherten Schemaexporte. Ein unverändertes Verzeichnis erfordert weiterhin einen Schemavergleich für die genutzten Vorgänge. Anfrageparameter, Textschemata, Antwortschemata und Berechtigungen können sich ohne Hinzufügen oder Entfernen eines Pfads ändern.
Führen Sie nach dem statischen Vergleich eine kleine Testsuite mit synthetischen Datensätzen aus: autorisiertes Lesen, gültiges Schreiben, ungültige Eingabe, fehlende Entität, leeres Ergebnis und relevanter Shop-Umfang. Prüfen Sie das persistente Ergebnis jedes Schreibvorgangs.
Erfassen Sie keine Tokens in Testdaten und committen Sie keine rohen Produktionsantworten. Schwärzen Sie Kennungen, wo angemessen, und verwenden Sie synthetische Kundendaten, damit Vertragsnachweise sicher mit Betreuern geteilt werden können.
Fehlende von inkompatibler Unterstützung unterscheiden
Fehlt ein Vorgang im Kandidatenschema, dokumentieren Sie ihn als in diesem Versionspaar nicht verfügbar. Senden Sie keine geratene Anfrage und interpretieren Sie einen Routing-Fehler nicht als Beleg für eine defekte neue Domänenimplementierung.
Existiert der Vorgang, lehnt aber eine dokumentierte Nutzlast ab, bewahren Sie den Schemaauszug sowie bereinigte Anfrage und Antwort auf. Dies ist eine andere Klasse von Kompatibilitätsproblem und lässt sich mit einem präzisen Vertragsunterschied melden.
Bewahren Sie bei generierten Clients die Revision des generierten Codes neben dem Schemaexport auf. Andernfalls kann ein Entwickler einen aktuellen Server mit einem alten Client testen und die Serialisierungsentscheidung des Clients dem Server zuschreiben. Reproduzieren Sie mit einer minimalen unterstützten Anfrage, bevor Sie eine Seite ändern.
Diese Unterscheidungen machen einen API-Migrationsbericht handlungsfähig: nicht verfügbarer Vorgang, Schemaabweichung, Serialisierungsfehler und Geschäftsvalidierungsfehler weisen jeweils auf unterschiedliche Verantwortliche hin.
Den Client gegen ein benanntes Versionspaar veröffentlichen
Eine Kompatibilitätsaussage sollte Core- und Ressourcenmodulversionen, übernommene Vorgänge und Einschränkungen benennen. Fehlt ein neuer Vorgang, deaktivieren Sie die abhängige Funktion ausdrücklich, statt später in einem unbeteiligten Ablauf zu scheitern.
Liefert ein Vorgang nach einer Zeitüberschreitung ein unsicheres Ergebnis, gleichen Sie es vor der Wiederholung eines folgenreichen Schreibvorgangs ab. Die Schemaverbesserungen in Version 9.2 beseitigen die Fehlermöglichkeiten verteilter Systeme nicht.
Die Hauptaufgabe des Entwicklers ist daher eng gefasst: Prüfen Sie den tatsächlichen Ressourcenvertrag, testen Sie die benötigten Versanddienstleister- und Zuordnungsänderungen und bewahren Sie Nachweise dafür, dass die Annahmen des Clients weiterhin gelten. Das ist zuverlässiger, als das neue Release als Einladung zur blinden Neugenerierung sämtlicher Komponenten zu behandeln.
Zum Kontext der zugrunde liegenden Plattform sehen Sie sich unseren Leitfaden zur PrestaShop-9-Admin-API an und wenden Sie die obigen versionsspezifischen Prüfungen auf die Installation an, die Sie bewerten.
Wenn Sie eine Erweiterung auswählen, sehen Sie sich die PrestaShop-9-Module von PrestaSuite an und gleichen Sie die dokumentierte Versionsunterstützung und Integrationsanforderungen mit Ihren eigenen Testergebnissen ab.