1. Was ein guter Endpoint leisten muss

Ein Custom REST API Endpoint Magento 2 ist nicht einfach nur ein technischer Einstiegspunkt. Er ist Teil deiner öffentlichen oder internen Systemgrenze. Andere Systeme, Frontends, Integrationen oder Middleware verlassen sich darauf, dass der Endpoint stabil, dokumentierbar und berechtigbar ist. Genau deshalb sollte ein eigener Endpoint nicht wie ein schneller Controller-Hack gebaut werden.

Ein sauberer Magento-Endpoint basiert auf Service Contracts. Das bedeutet: Das eigentliche Verhalten liegt in einer API-Schnittstelle und deren Implementierung, nicht direkt in einer Route oder in einer unstrukturierten Klasse. webapi.xml verbindet HTTP-Methode und URL mit dieser Service-Schicht. ACL-Ressourcen legen fest, wer den Endpoint aufrufen darf. Token oder Session-Kontext entscheiden über Authentifizierung. Wenn diese Teile sauber getrennt sind, bleibt die API wartbar.

Für dieses Tutorial bauen wir einen einfachen Endpoint, der eine Begrüßungsnachricht liefert. Das fachliche Beispiel ist bewusst klein, damit die technische Struktur klar bleibt. In echten Projekten kann derselbe Aufbau für Bestandsabfragen, ERP-Synchronisation, CRM-Integrationen oder Headless-Funktionen verwendet werden. Der entscheidende Punkt ist: Ein Custom REST API Endpoint Magento 2 sollte immer wie ein Service entworfen werden, nicht wie ein isolierter Request-Handler.

2. Service Contract und Interface

Der erste Baustein ist das API-Interface. Wenn du einen Custom REST API Endpoint Magento 2 bauen willst, solltest du die öffentliche Methode zuerst als Service Contract formulieren. Dieser Vertrag definiert Eingaben, Rückgabewerte und Exceptions. Dadurch kann später nicht nur REST, sondern auch anderer Magento-Code dieselbe Funktion nutzen.

Wir legen im Beispiel das Interface unter app/code/Mironsoft/ApiDemo/Api/HelloInterface.php ab. Es enthält eine Methode getMessage(), die eine Zeichenkette zurückgibt. Für komplexere Antworten würde man stattdessen Data Interfaces oder DTO-nahe Strukturen verwenden. Wichtig ist, dass der Vertrag explizit bleibt und nicht von zufälligen Arrays abhängt.

<?php
declare(strict_types=1);

namespace Mironsoft\ApiDemo\Api;

/**
 * Public service contract for the example REST endpoint.
 */
interface HelloInterface
{
    /**
     * Returns a greeting message for the API consumer.
     */
    public function getMessage(): string;
}

Dieser Schritt wird oft übersprungen, wenn ein Team schnell liefern will. Genau dort beginnen aber spätere Probleme. Ohne Service Contract ist unklar, ob ein Endpoint intern und extern dieselbe Verantwortung trägt, wie er getestet wird und welche Kompatibilität bei Änderungen gilt. Ein Custom REST API Endpoint Magento 2 ohne Interface wirkt kurzfristig schneller, kostet aber später mehr Wartung.

3. Implementierung und Dependency Injection

Nach dem Interface kommt die Implementierung. Sie liegt üblicherweise in Model oder in einer klar abgegrenzten Service-Klasse. Die Implementierung sollte fachlich arbeiten und keine REST-spezifischen Details kennen. Kein Lesen von Headern, keine direkte Response-Manipulation, keine URL-Logik. Diese Trennung macht die Klasse testbar und wiederverwendbar.

Im Beispiel kommt die Implementierung nach app/code/Mironsoft/ApiDemo/Model/Hello.php. Danach verknüpft etc/di.xml das Interface mit der konkreten Klasse. Genau so nutzt Magento Dependency Injection sauber.

<?php
declare(strict_types=1);

namespace Mironsoft\ApiDemo\Model;

use Mironsoft\ApiDemo\Api\HelloInterface;

/**
 * Service implementation for the example REST endpoint.
 */
final class Hello implements HelloInterface
{
    /**
     * Returns the API greeting message.
     */
    public function getMessage(): string
    {
        return 'Hello from Mironsoft API Demo.';
    }
}

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="Mironsoft\ApiDemo\Api\HelloInterface"
                type="Mironsoft\ApiDemo\Model\Hello"/>
</config>

Wenn der Endpoint reale Daten liefert, injizierst du hier Repositories, SearchCriteriaBuilder, Validatoren oder andere Services. Genau an dieser Stelle zahlt sich saubere Magento-Architektur aus. Ein REST Endpoint sollte nicht direkt mit dem ObjectManager arbeiten und auch nicht anfangen, SQL oder Collections wild im Service zu mischen. Die API-Schicht profitiert direkt von denselben Standards wie der restliche Anwendungscode.

4. webapi.xml und ACL

Jetzt kommt die eigentliche REST-Freigabe. Die Datei app/code/Mironsoft/ApiDemo/etc/webapi.xml beschreibt URL, HTTP-Methode, Service-Klasse und ACL-Ressource. Hier entscheidet sich, wie Magento den Endpoint nach außen verfügbar macht. Ein Custom REST API Endpoint Magento 2 lebt also nicht im Controller, sondern in der Verknüpfung von Service Contract und webapi.xml.

Im Beispiel verwenden wir einen GET-Endpoint unter /V1/mironsoft/hello. Für einfache Leseoperationen passt GET. Schreibende Operationen sollten POST, PUT oder DELETE sauber nach Semantik wählen. Die ACL-Ressource bestimmt, welche Token oder Benutzerrollen den Endpoint verwenden dürfen.

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route url="/V1/mironsoft/hello" method="GET">
        <service class="Mironsoft\ApiDemo\Api\HelloInterface" method="getMessage"/>
        <resources>
            <resource ref="Mironsoft_ApiDemo::hello"/>
        </resources>
    </route>
</routes>

Zusätzlich braucht das Modul eine ACL-Ressource. Sie liegt in etc/acl.xml. Ohne diese Ressource ist die Freigabe nicht sauber. Viele Entwickler setzen bei internen Endpoints vorschnell anonymous. Das ist nur dann vertretbar, wenn der Endpoint wirklich öffentlich und technisch harmlos ist. Für Geschäfts- oder Integrationsdaten ist eine gezielte ACL fast immer die bessere Wahl.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Mironsoft_ApiDemo::root" title="Mironsoft API Demo" sortOrder="10">
                    <resource id="Mironsoft_ApiDemo::hello" title="Hello Endpoint" sortOrder="10"/>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

Diese Trennung ist wichtig: webapi.xml sagt, welcher Service über HTTP erreichbar ist. acl.xml sagt, wer ihn nutzen darf. Ein robuster Custom REST API Endpoint Magento 2 braucht beides. Sonst endet man schnell bei Endpoints, die zwar laufen, aber weder sicher noch sauber dokumentiert sind.

5. Token und Authentifizierung

Der Titel des Themas nennt ausdrücklich den Token, und das zu Recht. Ein REST Endpoint ist erst praktisch nutzbar, wenn klar ist, wie er authentifiziert wird. Magento kennt dafür unterschiedliche Wege: Admin-Token, Customer-Token, Session-basierte Kontexte und anonyme Endpoints. Welche Variante passt, hängt vom Zweck der API ab.

Für interne Integrationen, Backoffice-Synchronisation oder System-zu-System-Kommunikation ist ein Admin-Token oft die einfachste Lösung. Für Kundenfunktionen im Headless-Frontend ist eher ein Customer-Token relevant. Öffentliche Endpoints sollten sehr sparsam und bewusst eingesetzt werden. Nur weil ein Endpoint technisch anonym freigegeben werden kann, heißt das nicht, dass es fachlich sinnvoll ist.

Ein typischer Ablauf für einen Admin-Token beginnt mit dem Request an /rest/V1/integration/admin/token. Danach wird der Token im Authorization-Header als Bearer-Token mitgeschickt. Erst dann kann der auf ACL geschützte Endpoint aufgerufen werden. Das ist der Punkt, an dem viele Tests scheitern: Der Endpoint selbst ist korrekt, aber der falsche Token oder die falsche ACL verhindert den Zugriff.

curl -X POST "https://example.test/rest/V1/integration/admin/token" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"adminPassword"}'

curl -X GET "https://example.test/rest/V1/mironsoft/hello" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json"

Für produktive Integrationen ist zusätzlich wichtig, wie Tokens rotiert, geloggt und abgesichert werden. Ein sauber gebauter Custom REST API Endpoint Magento 2 endet nicht bei der XML-Datei. Betrieb, Monitoring und Zugriffskontrolle gehören dazu, besonders wenn ERP, PIM oder externe SaaS-Systeme auf die API zugreifen.

6. Typische Fehler

Die häufigsten Fehler bei eigenen Endpoints sind erstaunlich konstant. Erstens wird direkt eine Klasse an webapi.xml gehängt, ohne Service Contract. Zweitens wird ACL zu offen definiert. Drittens mischt die Implementierung HTTP-Logik, Datenzugriff und Business-Logik in einer einzigen Klasse. Viertens werden Rückgabewerte als lose Arrays ohne klaren Vertrag gebaut. Fünftens wird die API nur lokal getestet, aber nicht mit realem Token-Flow.

Ein weiterer Fehler ist die falsche Erwartung an REST selbst. Nicht jede interne Funktion braucht automatisch einen REST Endpoint. Wenn nur Magento-intern auf eine Funktion zugegriffen wird, reicht oft ein normaler Service. Ein Custom REST API Endpoint Magento 2 ist sinnvoll, wenn externe oder entkoppelte Systeme dieselbe Funktion stabil und kontrolliert aufrufen sollen.

Auch Naming ist relevant. URLs wie /V1/doSomething oder /V1/customapi/test sind technisch möglich, aber schlecht wartbar. Besser sind klar benannte Ressourcen mit fachlicher Bedeutung. Wer APIs ernst nimmt, baut nicht nur die Technik, sondern auch eine verständliche Schnittstelle.

7. REST Endpoint vs. Controller

Ein Magento-Controller und ein REST Endpoint wirken auf den ersten Blick ähnlich, weil beide auf HTTP reagieren. Der Unterschied ist architektonisch trotzdem erheblich. Ein Controller ist Teil der Web-Anwendung und liefert meist HTML oder Redirects. Ein REST Endpoint ist eine API-Schnittstelle mit maschinenlesbarem Vertrag, definierter Authentifizierung und langfristiger Integrationsverantwortung.

Der Vergleich hilft bei Architekturentscheidungen. Wenn eine externe App, ein ERP oder ein Headless-Frontend auf Daten zugreifen soll, ist ein sauberer Endpoint die richtige Wahl. Wenn eine Magento-Seite HTML rendern soll, ist ein Controller passender. Ein Controller als API-Abkürzung zu missbrauchen, rächt sich meistens schnell.

9. Zusammenfassung

Ein Custom REST API Endpoint Magento 2 besteht aus mehr als einer URL. Der saubere Weg führt über Service Contract, Interface, Implementierung, Dependency Injection, webapi.xml, ACL und einen durchdachten Token-Flow. Diese Trennung macht die API testbar, erweiterbar und integrationsfähig.

Wer schnelle Abkürzungen über Controller, ObjectManager oder unklare Arrays nimmt, spart nur kurzfristig Zeit. Für produktive Magento-Integrationen lohnt sich ein sauberer Endpoint-Aufbau fast immer, weil spätere Änderungen kontrollierbar bleiben.

10. FAQ: Custom REST API Endpoint in Magento 2