REST-Webapi-Interfaces in Magento auf Vertragstreue testen

1. Warum Vertragstreue bei REST-Webapi-Interfaces ein eigenes Testthema ist

Magentos REST-API funktioniert ueber das Prinzip der Service Contracts: Eine Api\Interface-Datei definiert die vom Aussen sichtbare Methode inklusive Parametertypen und Rueckgabetyp, und webapi.xml bindet einen HTTP-Endpunkt an genau diese Methode. Die eigentliche Implementierung liegt in einer Model-Klasse, die das Interface umsetzt. Diese drei Artefakte, Interface, webapi.xml und Implementierung, muessen exakt zusammenpassen, damit die REST-API stabil und vorhersagbar bleibt.

In der Praxis driften diese drei Ebenen ueber die Zeit leicht auseinander: Ein Entwickler fuegt der Implementierung ein zusaetzliches optionales Argument hinzu, ohne das Interface anzupassen, oder aendert einen Rueckgabetyp, ohne zu bedenken, dass externe API-Konsumenten sich auf die alte Struktur verlassen. Ohne automatisierte Pruefung fallen solche Abweichungen oft erst auf, wenn ein Partnersystem ploetzlich Fehler meldet, weil sich die tatsaechliche API-Antwort veraendert hat.

2. Die drei Vertragsebenen und ihre jeweilige Fehlerquelle

Die erste Ebene ist die Uebereinstimmung zwischen Interface und Implementierung: Implementiert die Model-Klasse tatsaechlich alle im Interface deklarierten Methoden mit exakt passenden Parametertypen und Rueckgabetypen. PHP selbst erzwingt das durch die implements-Klausel bereits auf Sprachebene, doch bei nullable Typen, Default-Werten oder Union-Types kann es feine Abweichungen geben, die PHP nicht als Fehler erkennt, aber dennoch das erwartete Verhalten der API veraendern.

Die zweite Ebene ist die Uebereinstimmung zwischen webapi.xml und dem Interface: Referenziert der route-Eintrag tatsaechlich die korrekte Interface-Methode mit dem korrekten Namespace, und stimmen die in webapi.xml deklarierten Parameter-Constraints mit den tatsaechlichen Methodensignaturen ueberein. Die dritte Ebene ist die Stabilitaet der Rueckgabestruktur ueber die Zeit, also ob sich das serialisierte JSON-Format zwischen zwei Releases unbeabsichtigt aendert.

3. Interface-Implementierungs-Konsistenz per Reflection automatisiert pruefen

PHPUnit kann mit der ReflectionClass systematisch pruefen, ob eine Implementierungsklasse tatsaechlich alle Methoden eines Interfaces mit identischer Signatur bereitstellt, auch ueber Aspekte hinaus, die PHP selbst nicht erzwingt, etwa ob PHPDoc-Typangaben fuer Array-Elemente konsistent sind. Ein generischer Test, der eine Liste von Interface-Implementierungs-Paaren durchlaeuft, deckt so alle Service Contracts eines Moduls in einem einzigen Testlauf ab.

Dieser Ansatz skaliert gut, weil neue Service Contracts einfach als zusaetzlicher Eintrag in die Paarliste aufgenommen werden, ohne fuer jeden einzelnen Contract einen eigenen, manuell gepflegten Test schreiben zu muessen. Der Test wird dadurch zu einer Art Inventarpruefung, die bei jedem CI-Lauf automatisch sicherstellt, dass kein Contract unbemerkt aus dem Ruder laeuft.

<?php
declare(strict_types=1);

namespace Mironsoft\SeoSuite\Test\Unit\Api;

use PHPUnit\Framework\TestCase;

class ServiceContractConsistencyTest extends TestCase
{
    /**
     * @dataProvider interfaceImplementationPairsProvider
     */
    public function testImplementationMatchesInterfaceSignature(string $interface, string $implementation): void
    {
        $this->assertTrue(
            in_array($interface, class_implements($implementation), true),
            "$implementation must implement $interface"
        );

        $interfaceMethods = get_class_methods($interface);
        foreach ($interfaceMethods as $methodName) {
            $interfaceMethod = new \ReflectionMethod($interface, $methodName);
            $implMethod = new \ReflectionMethod($implementation, $methodName);

            $this->assertSame(
                (string) $interfaceMethod->getReturnType(),
                (string) $implMethod->getReturnType(),
                "Return type mismatch for $interface::$methodName"
            );

            $this->assertSame(
                $interfaceMethod->getNumberOfParameters(),
                $implMethod->getNumberOfParameters(),
                "Parameter count mismatch for $interface::$methodName"
            );
        }
    }

    public static function interfaceImplementationPairsProvider(): array
    {
        return [
            'RedirectRuleRepository' => [
                \Mironsoft\SeoSuite\Api\RedirectRuleRepositoryInterface::class,
                \Mironsoft\SeoSuite\Model\RedirectRuleRepository::class,
            ],
            'RedirectRuleManagement' => [
                \Mironsoft\SeoSuite\Api\RedirectRuleManagementInterface::class,
                \Mironsoft\SeoSuite\Model\RedirectRuleManagement::class,
            ],
        ];
    }
}

4. webapi.xml gegen das tatsaechliche Interface validieren

Um sicherzustellen, dass webapi.xml keine veralteten oder falsch geschriebenen Referenzen enthaelt, wird die Datei in einem Test per SimpleXML eingelesen und fuer jeden route-Eintrag geprueft, ob die referenzierte Klasse und Methode tatsaechlich existieren und ob der Klassenname einem Interface entspricht, das das erwartete Naming-Pattern erfuellt. Ein solcher Test faengt den haeufigen Fehler ab, dass nach einem Refactoring eine Methode umbenannt wird, aber die Referenz in webapi.xml vergessen wird.

Zusaetzlich lohnt sich eine Pruefung, ob die in webapi.xml deklarierten resources, also die ACL-Berechtigungen fuer den Endpunkt, tatsaechlich in acl.xml existieren. Eine Route, die auf eine nicht existierende ACL-Ressource verweist, fuehrt dazu, dass niemand jemals Zugriff auf den Endpunkt erhaelt, was in der Praxis erst durch eine 403-Antwort im laufenden Betrieb auffaellt, wenn kein automatisierter Test diese Konsistenz vorher geprueft hat.

<?php
declare(strict_types=1);

public function testWebapiXmlReferencesExistingInterfaceMethods(): void
{
    $xml = simplexml_load_file(__DIR__ . '/../../../etc/webapi.xml');

    foreach ($xml->route as $route) {
        $service = $route->service;
        $className = (string) $service['class'];
        $methodName = (string) $service['method'];

        $this->assertTrue(
            interface_exists($className) || class_exists($className),
            "Referenced service class $className does not exist"
        );
        $this->assertTrue(
            method_exists($className, $methodName),
            "Method $methodName does not exist on $className"
        );
    }
}

5. Die serialisierte Rueckgabestruktur mit einem Snapshot-Vergleich stabil halten

Selbst wenn Interface und Implementierung uebereinstimmen, kann sich das tatsaechliche JSON-Format der API-Antwort veraendern, etwa wenn ein DataObject um ein neues Feld erweitert wird, das automatisch mitserialisiert wird, obwohl es fuer externe Konsumenten nicht gedacht war. Ein Snapshot-Test, der die Serialisierung des Rueckgabewerts gegen eine zuvor gespeicherte, erwartete Struktur vergleicht, macht solche Aenderungen sichtbar, bevor sie in Produktion gehen.

Der Test ruft die Service-Methode mit festen Testdaten auf, serialisiert das Ergebnis genauso, wie es der Webapi-Layer tun wuerde, und vergleicht es mit einer im Repository abgelegten Referenzdatei. Weicht die Struktur ab, muss ein Entwickler bewusst entscheiden, ob es sich um eine beabsichtigte, dokumentierte Aenderung handelt, die die Referenzdatei aktualisiert, oder um eine versehentliche Abweichung, die korrigiert werden muss.

<?php
declare(strict_types=1);

public function testGetRedirectRuleResponseStructureMatchesSnapshot(): void
{
    $service = $this->objectManager->create(RedirectRuleManagementInterface::class);
    $result = $service->getByPath('/old-path');

    $serialized = $this->serializer->serialize([
        'from_path' => $result->getFromPath(),
        'to_path' => $result->getToPath(),
        'redirect_type' => $result->getRedirectType(),
    ]);

    $expected = file_get_contents(__DIR__ . '/_files/get_redirect_rule_response.json');
    $this->assertJsonStringEqualsJsonString($expected, $serialized);
}

6. Breaking Changes gezielt von erweiternden Aenderungen unterscheiden

Nicht jede Aenderung an einer API ist ein Breaking Change. Ein neues optionales Feld in der Antwort ist in der Regel unproblematisch, weil bestehende Konsumenten es einfach ignorieren koennen. Ein entferntes Feld, ein umbenanntes Feld oder ein geaenderter Datentyp, etwa von String zu Integer, bricht dagegen bestehende Integrationen. Ein guter Vertragstreue-Test unterscheidet explizit zwischen diesen Faellen, statt bei jeder Aenderung pauschal fehlzuschlagen.

In der Praxis bedeutet das, dass ein Test fuer entfernte oder umbenannte Felder immer fehlschlaegt, waehrend fuer neue Felder eine bewusste Positivliste gepflegt wird, die dokumentiert, welche Erweiterungen bereits akzeptiert wurden. Dieser Ansatz zwingt Entwickler dazu, jede Erweiterung der API bewusst zu dokumentieren, statt sie unbemerkt durchrutschen zu lassen, was insbesondere bei extern genutzten APIs wichtig fuer Versionierungsentscheidungen ist.

<?php
declare(strict_types=1);

public function testResponseStructureHasNoRemovedOrRenamedFields(): void
{
    $baselineFields = ['from_path', 'to_path', 'redirect_type'];
    $currentFields = array_keys($this->getCurrentResponseStructure());

    $missingFields = array_diff($baselineFields, $currentFields);
    $this->assertEmpty($missingFields, 'Removed or renamed fields: ' . implode(', ', $missingFields));
}

public function testNewFieldsAreExplicitlyAcknowledged(): void
{
    $acknowledgedNewFields = ['redirect_note'];
    $currentFields = array_keys($this->getCurrentResponseStructure());
    $baselineFields = ['from_path', 'to_path', 'redirect_type'];

    $unacknowledgedFields = array_diff($currentFields, $baselineFields, $acknowledgedNewFields);
    $this->assertEmpty(
        $unacknowledgedFields,
        'New fields must be explicitly acknowledged: ' . implode(', ', $unacknowledgedFields)
    );
}

7. Parameter-Constraints und Pflichtfelder aus webapi.xml gegen die Methodensignatur pruefen

webapi.xml erlaubt es, ueber das parameters-Element bestimmte Constraints wie force-Werte fuer optionale Parameter zu deklarieren. Diese Deklarationen muessen zur tatsaechlichen Methodensignatur passen: Ein als optional deklarierter Parameter in webapi.xml, der in der PHP-Methode aber keinen Default-Wert besitzt, fuehrt zu Laufzeitfehlern, sobald ein Konsument den Parameter tatsaechlich weglaesst.

Ein gezielter Test iteriert ueber alle parameters-Eintraege in webapi.xml und vergleicht sie per Reflection mit den tatsaechlichen Parametern der Zielmethode, inklusive der Frage, ob ein Default-Wert vorhanden ist, wo webapi.xml einen force-Wert deklariert. Diese Pruefung deckt eine Fehlerklasse ab, die in der Praxis oft erst durch einen fehlgeschlagenen API-Aufruf eines Drittsystems auffaellt.

<?php
declare(strict_types=1);

public function testOptionalWebapiParametersHaveMatchingDefaultsInMethod(): void
{
    $xml = simplexml_load_file(__DIR__ . '/../../../etc/webapi.xml');

    foreach ($xml->route as $route) {
        $className = (string) $route->service['class'];
        $methodName = (string) $route->service['method'];
        $reflection = new \ReflectionMethod($className, $methodName);

        foreach ($route->parameters->parameter ?? [] as $param) {
            $paramName = (string) $param['name'];
            if (isset($param['force'])) {
                $reflectionParam = $this->findParameterByName($reflection, $paramName);
                $this->assertTrue(
                    $reflectionParam->isDefaultValueAvailable(),
                    "Parameter $paramName is forced in webapi.xml but has no default in $className::$methodName"
                );
            }
        }
    }
}

8. Vertragstreue-Tests fest in die CI-Pipeline einbetten

Damit Vertragstreue-Tests ihren vollen Nutzen entfalten, muessen sie bei jedem Merge-Request automatisch laufen, nicht nur gelegentlich manuell. Da diese Tests reine Unit-Tests ohne Datenbank oder HTTP-Layer sind, laufen sie schnell genug, um in jeder CI-Pipeline ohne spuerbare Verzoegerung mitzulaufen, im Gegensatz zu vollen API-Integrationstests, die typischerweise separat und seltener ausgefuehrt werden.

Ein sinnvoller Ausbauschritt ist, die Snapshot-Referenzdateien im Code-Review sichtbar zu machen: Aendert sich eine Referenzdatei in einem Merge-Request, sollte das Review-Team bewusst pruefen, ob diese Aenderung beabsichtigt und mit dem Team fuer API-Konsumenten abgestimmt ist, bevor der Merge-Request akzeptiert wird.

9. Checkliste fuer vertragstreue REST-Webapi-Interfaces

Wer neue REST-Endpunkte in Magento entwickelt, sollte automatisierte Tests fuer alle drei Vertragsebenen einplanen: Interface-Implementierungs-Konsistenz per Reflection, webapi.xml-Validierung gegen die tatsaechlichen Klassen und Methoden, sowie Snapshot-Tests fuer die serialisierte Antwortstruktur. Zusammen bilden diese drei Ebenen ein Sicherheitsnetz, das Breaking Changes zuverlaessig vor dem Release abfaengt.

Die folgende Tabelle fasst die verschiedenen Vertragstreue-Testebenen zusammen und zeigt, welche Fehlerklasse jede Ebene abdeckt.

10. Zusammenfassung

11. FAQ: REST-Webapi-Vertragstreue testen: Das Wichtigste auf einen Blick