Wie benutzt man die interne Shopware API und wie kann man Shop-Inhalte darüber erweitern?
Wenn es um den Verkauf von Produkten und die digitale Repräsentation des eigenen Unternehmens im Internet geht, denken viele Händler oft an die große Online-Shop-Plattform Shopware und setzen sich tiefgreifender mit deren technologischen Details auseinander. Besonders Shopware in der Version 6 bietet dabei interessante Ansätze durch eine moderne Architektur, die aus bewährten Softwarekomponenten besteht und sich auf den sog. ‚API-First‘ Ansatz stützt, d.h. alle vorhandenen Bausteine können untereinander über die API kommunizieren und sämtliche Daten können per Schnittstelle abgefragt werden. Dieser Beitrag soll vor allem eine Einführung in dieses Konzept bieten und dessen Funktionalität und Möglichkeiten offenlegen.
1. Allgemeine Konzepte des Application Programming Interface
Die Programmierschnittstelle (englisch Application Programming Interface / API) ist der Bestandteil des Shopware-Technologiestacks, der die Kommunikation zwischen sämtlichen Bestandteilen des E-Commerce-Systems sicherstellt. So können alle Komponenten (der Core, die Administrationstools im Backend-Bereich und die Storefront) Daten untereinander austauschen, also Abfragen durchführen und neue Informationen in der hinter dem System liegenden Datenbank erstellen, lesen, modifizieren oder löschen (auch bekannt als die sog. “CRUD” (create, read, update, delete)-Operationen). Diese finden grundsätzlich statt, sobald im Administrationsbereich Einstellungen vorgenommen werden, aber auch, um die Darstellung des Shop-Frontends mit den passenden Daten laden zu können.
Während der Anwendung im Alltag und auch der Navigation im Online-Shop finden alle benötigten Verarbeitungsschritte der Schnittstelle automatisch und im Hintergrund statt, sodass der Käufer davon wenig mitbekommt.
Die Vorgehensweise kann aber ebenso für eigene Anwendungszwecke implementiert werden, um individuelle Erweiterungen für das Open-Source-System zu realisieren oder selbst bestimmen zu können, auf welche Art und Weise eigene Daten von der Software verarbeitet werden sollen, wie es für einen Datenimport benötigt wird. Auch Warenwirtschaftssysteme, Versand- und Bezahldienstleister nutzen diese Möglichkeiten.
Voraussetzung ist ein Software-Client, der die Aufrufe an die Schnittstelle über einen HTTP-Request (Bestandteil des weitverbreiteten Internetprotokolls) absetzen kann und darüber Zugriff auf die Daten erlangt, die über die API mit der Datenbank ausgetauscht werden. Der Softwarestack bei einer Shopware 6 – Installation unterstützt diese Operationen bereits von Haus aus durch das PHP-Framework Symfony, auf dem das E-Commerce System basiert.
2. Technische Details und Hintergründe bei der Verwendung
Shopware implementiert seine Schnittstelle nach dem REST-Prinzip, was ausgeschrieben ‚Representational State Transfer‘ bedeutet. Dieses schreibt bestimmte Regeln vor, nach denen der Austausch von Daten stattfinden darf.
Es existieren verschiedene Typen von Methoden, die darüber bestimmen, nach welchem Schema ein Request verarbeitet werden soll. Dabei kommen ‚POST‘, ‚PATCH‘, ‚GET‘ und ‚DELETE‘ vorwiegend neben weiteren Möglichkeiten zum Einsatz. GET liefert angefragte Daten nur an den Client zurück, POST legt neue Daten in der Datenbank an. DELETE ist dafür zuständig, bereits bestehende Datensätze zu löschen, wohingegen man durch die HTTP-Methode PATCH gezielt bestimmte Werte eines bereits vorhandenen Datensatzes ändern bzw. aktualisieren kann.
Als zweiter wichtiger Bestandteil für die Anfrage an die Shopware-API kommt noch der Endpunkt oder – einfach gesagt – die URL für eine bestimmte Ressource zum Einsatz. Für das Shopware 6-Umfeld ist definiert, dass beim Aufruf der Schnittstelle der Endpunkt ‚/api‘ an die Hauptdomain angehängt wird und so die Voraussetzung dafür liefert, Daten von allen Objekten wie Produkten, Kunden, Produktbildern, etc. abrufen zu können. Diese stehen dann unter ihren englischsprachigen Begriffen, also ‚/product‘, ‚customer‘, ‚/media‘ usw. als Endpunkt zur Verfügung.
3. Umgang mit Daten von der Shopware-API
Wenn der Endpunkt ‚/api/order‘ einer Domain für die Ausgabe aller bestehenden Bestellungen für diesen Shop angesprochen wird, handelt es sich bei der Antwort des Requests um die Gesamtmenge aller verfügbaren Daten in diesem Zusammenhang. Gezieltere Ergebnisse können erreicht werden, indem die ID eines bestimmten Eintrags zusätzlich in der URL verwendet wird. Diese Nummer wird automatisch intern von der Schnittstelle erstellt und jedem Eintrag zur eindeutigen Identifikation zugeordnet. So würde die Anfrage an den Domain-Endpunkt der Form /api/order/19a2038dd7546u5f alle Daten, die mit dieser speziellen Bestellung zusammenhängen, im JSON-Format (Datenaustauschformat JavaScript Object Notation) zurückliefern. Dazu gehören Schlüssel-Werte Paare, die einfache Angaben wie die Gesamtartikelanzahl der gekauften Waren sein können, andererseits auch als Menge weiter untergliedert werden, sodass z.B. die einzelnen Posten einer getätigten Bestellung in einer solchen Menge enthalten sind. Diese sind wiederum identisch mit den Rückgaben wie sie bei einer GET-Anfrage an den Endpunkt für Produkte im Shopware-Shop entstehen würden.
Zusätzlich können gezielt Suchvorgänge über die Schnittstelle durchgeführt werden, beispielsweise nach allen Artikeln mit einer bestimmten Kategorie. Hierfür wird ergänzend der Schnittstellenaufruf um den Zusatz ‚/search‘ ergänzt. Die Suchkriterien werden anschließend über den Request im JSON-Format mitgegeben. Als Rückantwort wird auch hier eine Menge an Produkten zurückgegeben, diesmal allerdings nach den angegebenen Kriterien gefiltert.
Besonders interessant ist die Verwendung der Schnittstelle für Entwickler, sobald sie die einfache Möglichkeit nutzen können, die Daten im Shop effizient anzupassen und zu verändern oder aktualisieren. Wie erwähnt findet hierbei die PATCH-Methode Anwendung, die als Besonderheit mit sich bringt, dass als Endpunkt eine bestimmte Ressource, also ein eindeutiges Produkt oder eine eindeutige Produktkategorie, benannt sein muss. Dann werden wieder die Eigenschaften des Objekts, die zu verändern sind, über die Anfrage im JSON-Format eingetragen und in der Anfrage mitgeschickt.
4. Allgemeine und zusammenfassende Informationen
Shopware benutzt die Aufrufe an die Schnittstelle vollständig im Hintergrund, wenn der Benutzer mit den Elementen in der Storefront interagiert oder der Shopbetreiber im Administrationsbereich über die Benutzeroberfläche Shopinhalte verwaltet. In der Adressleiste des Browsers sind beispielsweise dann Bestandteile von diesen Vorgängen zu sehen, wenn die Bearbeitung einer bestimmten Kategorie stattfindet – in diesem Fall ist ebenso die von Shopware vergebene, eindeutige ID als Bestandteil der URL zu sehen. Wie auch bei dem Anlegen neuer Objekte, z.B. Produkte, im Backend-Bereich existiert auch bei der Verwendung der API eine Pflicht zum Setzen von Pflichtfeldern. Ist einem Produkt keine Artikelnummer zugeordnet, so schlägt die Anfrage an die Schnittstelle fehl, vorausgesetzt, die Informationen existieren nicht bereits, wie es bei einem PATCH-Request der Fall wäre.
Interessant für Entwickler ist die programmiertechnische Nutzung, die nach dem Client-Server-Modell nach dem HTTP-Protokoll funktioniert, das auch bei der standardmäßigen Kommunikation im Web vorrangig Anwendung findet.
Hervorstechende Vorteile sind insbesondere die modulare und einfache Anbindung von Services und Produkten anderer Anbieter, außerdem die individuelle und effiziente Interaktion mit Shopinhalten durch Entwickler, denen umfangreiche Möglichkeiten zur Verfügung gestellt werden, alle Elemente und Daten ihres Online-Shops nach Belieben anzupassen.