Wenn Sie eine größere Website betreiben oder selbst Web-Entwickler:in sind, ist Ihnen die Abkürzung „API“ (oder der deutsche Begriff “Schnittstelle”) sicher schon mal zu Ohren gekommen. In diesem Blogbeitrag möchten wir eine kleine und wenig technische Einführung zu diesem Thema geben und gehen dabei insbesondere auf die Synchronisierung verschiedener Schnittstellen-Daten zu WordPress ein.

Als Agentur für Web-Entwicklung beschäftigen wir uns regelmäßig damit, Schnittstellendaten sicher und robust zwischen verschiedenen externen Systemen und WordPress auszutauschen.
Sprechen Sie uns gerne an, falls Sie individuelle Unterstützung benötigen.

Was genau ist eigentlich eine API?

Bevor wir diese Frage beantworten, lassen Sie uns einen kleinen Schritt zurücktreten. Um einen Computer zu nutzen, müssen Sie nicht verstehen, wie die Maschine selbst funktioniert: Sie interagieren stattdessen einfach über eine Benutzeroberfläche mit ihr. Manchmal ist die Benutzeroberfläche ganz einfach, beispielsweise eine Befehlszeile – wie der „DOS-Prompt“ von früher –, wo Sie Befehle eingeben, um den Computer etwas für Sie tun zu lassen. Zum Beispiel das Umbenennen einer Datei oder das Auflisten eines Verzeichnisinhalts.

Die meisten von uns nutzen inzwischen jedoch viel ausgefeiltere Benutzeroberflächen. Schließlich laufen private und geschäftliche Computer typischerweise mit Betriebssystemen wie Windows oder MacOS. Diese Betriebssysteme haben grafische Benutzeroberflächen, die das Ändern eines Dateinamens so einfach machen wie das Auswählen in einem Fenster und anklicken der passenden Option in einem Rechtsklick-Menü. Wenn Sie ein Textdokument schreiben möchten, öffnen Sie einfach eine Textverarbeitung und schon geht es los.

Kurz gesagt: Benutzeroberflächen ermöglichen es, auf sehr einfache Weise mit hochkomplexen Computern zu interagieren. Aber was, wenn die Computer selbst oder einzelne Programme miteinander kommunizieren sollen?

Hier kommen APIs – kurz für „Application Programming Interfaces“ – ins Spiel. Genau wie eine Benutzeroberfläche die inneren Abläufe eines Software-Programms vor den Benutzern verbirgt und es einfacher macht, eine bestimmte Aufgabe auszuführen, verbirgt auch eine API die inneren Abläufe des zugehörigen Programms, um die Interaktion zu erleichtern.

APIs im World Wide Web

Im Internet werden APIs verwendet, um Online-Anwendungen, wie Websites, Shops und Apps, die Kommunikation miteinander zu ermöglichen. Viele APIs folgen dabei einem Architekturstil, der als REST (Representational State Transfer) bezeichnet wird.

Als Agentur, die sich mit Webentwicklung beschäftigt, arbeiten wir sehr regelmäßig mit APIs aller Art. Wir setzen sie zum Beispiel häufig dafür ein, Daten von externen Quellen in die WordPress-Websites oder WooCommerce-Shops unserer Kunden zu importieren.

Ein Beispiel ist unser Kunde A-NULL, der eine selbst entwickelte Applikation zur Verwaltung von Kursen verwendet. Diese Applikation enthält alle Kursdaten und kümmert sich um die Teilnehmerregistrierung. Über eine eigens dafür entworfene API sorgen wir dafür, dass Kurse und Buchungsmöglichkeiten in Echtzeit auch im Online-Shop von A-NULL zur Verfügung stehen. Durch diese Schnittstelle ist es also nicht mehr notwendig, die Daten an zwei Stellen manuell zu pflegen – alles läuft voll automatisiert.

Individuelles Kursverwaltungssystem auf WordPress-Basis

Wie funktionieren APIs und Schnittstellen?

Eine Datenquelle,  z.B. eine andere Website oder der Webservice einer Applikation, verfügt über einen oder mehrere API-Endpoints. Diese Endpoints sind im Grunde nichts anderes als URIs, also Internetadressen, die man theoretisch auch in den Browser eingeben kann. Unter https://resonanz-digital.at/wp-json/wp/v2/posts finden Sie zum Beispiel den WordPress API-Endpoint, über den eine Übersicht unserer Blogbeiträge abgerufen werden kann.

Ein Endpunkt kann auch geschützt sein. Das kann mit Benutzernamen und Passwort oder in einigen Fällen mit einem API-Schlüssel passieren, der für einen bestimmten, vorher autorisierten API-Benutzer einzigartig ist. Um auf einen API-Endpoint zuzugreifen, müssen Sie also wissen, wo Sie ihn finden (die Adresse des Endpoints) und gegebenenfalls, welche Anmeldeinformationen Sie brauchen, um Zugang zu erhalten.

Zusätzlich kann es Einstellungen geben, um die Daten auf eine bestimmte Weise zu laden. Wenn beispielsweise eine besonders große Menge an Daten vorhanden ist, ist es normalerweise eine gute Idee, eine Art Mengenbegrenzung oder Seitenaufteilung zu verwenden, bei der nur kleinere Datenmengen ausgegeben werden. So können Sie bei der Programmierung der Schnittstelle sicherstellen, dass die Zeit, die für die Verarbeitung der Daten benötigt wird, nicht zu einem Timeout oder anderen technischen Problemen führt.

Ein genauerer Blick auf gängige Datenformate

Die meisten modernen APIs im Web verwenden die Datenformate JSON oder XML. Beide haben den Vorteil, dass sie nicht nur von Maschinen, sondern auch von Menschen gelesen werden können.

JSON (JavaScript Object Notation) wurde von JavaScript abgeleitet. Einer Skriptsprache, die Interaktivität auf Websites ermöglicht. Darüber funktionieren zum Beispiel das Ein- und Ausblenden von mobilen Menüs oder das Speichern von Daten, ohne die Seite neu laden zu müssen. Viele komplexe Webanwendungen werden fast ausschließlich mit JavaScript erstellt.

Das JSON-Format sieht sehr einfach aus: Elemente bestehen aus einem Feld mit einem bestimmten Namen (Schlüssel) und einem Wert. Zwei verschiedene Arten von Klammern werden verwendet, um Elemente einzuschließen: geschweifte Klammern schließen Objektliterale (die Schlüssel/Wert-Paare enthalten) ein, während eckige Klammern Array-Literale (eine Sammlung einander ähnlicher Elemente) einschließen.

Hier ist ein vereinfachtes Beispiel, um die Informationen über zwei Personen, Jack und Jill, zu speichern:

{
    "people": [
        {
            "first_name": "Jack",
            "last_name": "Smith",
            "birth_date": "1990-05-15"
        },
        {
            "first_name": "Jill",
            "last_name": "Johnson",
            "birth_date": "1985-10-22"
        }
    ]
}

Das XML-Format (Extensible Markup Language) wurde hauptsächlich erstellt, um Dokumente zu strukturieren. XML wird aber auch verwendet, um API-Daten zu strukturieren. Hier ist eine XML-Version des früheren JSON-Beispiels:

XML-Code Beispiel

Wie JSON ist auch XML darauf ausgelegt, für Menschen gut lesbar zu sein. Das Schlüsselkonzept ist hier der sogenannte “Node“ oder Knoten: Im obigen Beispiel ist „people“ ein Knoten, der selbst mehrere Knoten mit dem Namen „person“ hat, von denen jeder wiederum Knoten wie „first_name“ enthält, die einen bestimmten Wert haben (z. B. „Jack“, „Jill“).

JSON hat einen strikten Ansatz, wie die Daten strukturiert werden müssen. Im Gegensatz dazu ist XML lockerer. Das kann gelegentlich zu Problemen führen, wenn man versucht, eine standardisierte Lösung zu finden, um Daten von einem API-Endpunkt zu importieren. Zum Beispiel ist auch der folgende Code gültiges XML:

XML-Code Beispiel

In diesem Beispiel bleiben die Daten dieselben, aber die Namen der Nodes/Knoten sind nicht mehr eindeutig. Stattdessen verwenden wir Attribute wie „type“ und „format“, um zusätzliche Informationen über die betreffenden Daten zu übermitteln. Die verschiedenen Arten, wie XML-Daten aufbereitet werden können, machen die Verarbeitung zuweilen knifflig.

Importieren der Daten von einem API-Endpunkt

Bei Resonanz Digital bauen wir regelmäßig komplexe Websites, bei denen es notwendig ist, API-Endpunkten abzufragen. In vielen Fällen verwenden wir die Daten anschließend in WordPress weiter. Um nicht immer wieder ähnlichen Code schreiben zu müssen, haben wir ein eigenes API-Synchronisierungs-Plugin für WordPress entwickelt.

Unser Plugin, das derzeit noch rein für unseren internen Gebrauch bestimmt ist, bietet eine praktische Benutzeroberfläche, um zu definieren, welche Daten von welchem Endpunkt in WordPress importiert werden sollen. In WordPress erstellen wir benutzerdefinierte Post Types, um die Daten abzulegen. Ein Post Type ist nichts anderes als eine spezifische Sammlung von Feldern. WordPress bringt eine Reihe von vordefinierten Post Types mit, wie „Beiträge“ und „Seiten“. Weitere Post Types kann man selbst definieren und mit individuellen Felder für die Datenspeicherung versehen.

Um die API-Daten zu importieren, muss die Website eine Verbindung zu einem API-Endpunkt herstellen, die Daten herunterladen (als JSON oder XML) und diese dann Stück für Stück durchgehen, um sie in den festgelegten benutzerdefinierten Post Type zu importieren. Wenn alles gut geht, werden die Daten so als benutzerdefinierte Beiträge gespeichert, die alle abgefragten Daten enthalten.

Unser Plugin erleichtert den Umgang mit API-Endpunkten erheblich, indem es viele Routinefälle automatisch abdeckt. Dennoch gibt es Fälle, in denen die Daten für die Verwendung auf noch einmal erweitert oder verändert werden müssen. Für diese Fälle haben wir im Plugin Hooks vorgesehen und programmieren individuelle Funktionen, die das Plugin erweitern.

Um zu unserem Beispiel mit der Kursverwaltung von ganz oben zurückzukehren: Es ist zum Beispiel möglich, dass für jeden Kurs ein oder mehrere Standorte hinterlegt sind. Ein Standort in diesem Zusammenhang ist einfach der physische Ort, an dem der Kurs stattfindet. Diese Standorte möchten wir mit einer Umkreissuche auf der Website benutzerfreundlich auffindbar machen.

Dazu schreiben wir etwas benutzerdefinierten Code, der die API-Felder für Straßennamen, Hausnummer, Postleitzahl und Stadt nutzt, um die passenden GEO-Koordinaten von einer anderen Schnittstelle (z.B. Google Geocoding API) abzufragen und als zusätzliche Information in unserem Post Type zu speichern. Mit den so gewonnenen Geodaten lässt sich die geplante Umkreissuche dann sehr einfach realisieren.

Ein weiteres Beispiel wäre die Handhabung von Bildern: Angenommen ein API-Endpunkt enthält URLs von Bildern und wir möchten diese in die WordPress-Mediathek importieren: Nach dem Import der textlichen URLs können wir eine zusätzliche Aktion durchführen, für die wir wieder einen Hook mit individuellem  Code verwenden, um die Bilder herunterzuladen und als Attachment zum passenden Eintrag unseres Post Types hinzuzufügen. „Hotlinking“, d. h. das direkte Verlinken eines Bildes von einer externen Website, ist nämlich schlechte Netiquette und ein Import daher oft die bessere Option. Darüber hinaus macht das Vorhandensein der Bilder auf der eigenen Website es möglich, sie passend zuzuschneiden und besser zu komprimieren.

Synchronisieren der Daten von einem API-Endpunkt

Ein einmaliger Import ist großartig, wenn sich Daten nicht mehr ändern. Wenn Sie von einem anderen Content-Management-System zu WordPress wechseln möchten, könnten Sie beispielsweise API-Endpunkte verwenden (sofern das andere CMS diese anbietet), um alle Daten auf die neue Website zu übertragen. In diesem Fall müssten Sie den Import nur einmal durchführen, dann prüfen, ob alles korrekt ist, und können die alte Website im Anschluss einfach löschen.

In den meisten API-Anwendungsfällen ist es mit einem einmaligen Import aber nicht getan und es wird ein regelmäßiger Datenabgleich benötigt. In unserem Beispiel mit der Kursverwaltung werden im Laufe der Zeit neue Kurse hinzugefügt und alte Kurse, die bereits stattgefunden haben, werden entfernt. Außerdem müssen wir damit rechnen, dass sich Kursdaten jederzeit verändern können. Der Titel wird überarbeitet, eine neue Kursbeschreibung hinzugefügt oder das Datum ändert sich. Besonders relevant für die Buchung ist auch, wie viele Plätze noch verfügbar sind oder ob der Termin vielleicht schon ausgebucht ist.

Diese Veränderlichkeit der Kursdaten heißt für uns, dass wir den Endpunkt regelmäßig überprüfen und die neuen Datensätze mit denen vergleichen müssen, die wir bereits in unserem WordPress Post Type abgelegt haben. Sollten wir eine Änderung feststellen, gilt es die entsprechenden Daten punktgenau zu aktualisieren.

Automatische Aufgaben ausführen mit Cronjobs und WP-Cron

Die regelmäßige Überprüfungen stößt man in der Regel mit sogenannten „Cron-Jobs“ an. Das Wort „Cron“ leitet sich von „Chronos“, dem antiken griechischen Gott, der mit der Zeit in Verbindung gebracht wird, ab. Ein „richtiger“ Cron-Job ist ein Prozess, der auf dem Server eingerichtet wird, der eine Website hostet. Dort wird angegeben, welche Aufgabe in welchen Zeitabständen ausgeführt werden soll.

WordPress hat zusätzlich einen ähnlichen Mechanismus im Gepäck, der als „WP-Cron“ bezeichnet wird. Deren Zweck ist derselbe wie bei richtigen, serverseitigen Cron-Jobs: eine bestimmte Aufgabe (in diesem Fall innerhalb von WordPress) zu einem bestimmten Zeitpunkt auszuführen.

Weil WordPress, wie jede Website auch, nur dann ausgeführt wird, wenn eine URL aufgerufen wird, verlässt sich der WP-Cron für seine Funktion normalerweise darauf, dass auf der Website etwas passiert. Wenn ein Besucher eine Seite im Frontend oder Backend von WordPress aufruft, überprüft der WP-Cron im Hintergrund, ob irgendwelche geplanten Ereignisse gerade jetzt oder in der Vergangenheit hätten stattfinden sollen. Falls es solche Aufgaben gibt, wird ihre Ausführung gestartet.

Diese Abhängigkeit von Website-Besuchern bedeutet leider auch, dass auf Websites, die nur wenig besucht werden, viele Aufgaben später als beabsichtigt ausgeführt werden. Wenn beispielsweise eine Aufgabe zweimal täglich ausgeführt werden soll, aber an diesem Tag nur eine einzige Seite von auf der Website aufgerufen wird, kann die Aufgabe auch nur einmal ausgeführt werden. So etwas kann mit der Zeit zu einem ordentlichen Rückstau geplanter Aufgaben führen. In solchen Fällen ist es meist eine gute Idee, einen richtigen, serverseitigen Cron-Job einzurichten, der die Rolle der Website-Besucher übernimmt und WP-Cron ganz automatisch regelmäßig aufruft.

Für häufiger besuchte Websites, was zum Glück für die Mehrheit unserer Kundenwebsites gilt, ist die normale Funktionsweise des WP-Cron zwar ausreichend, um einen Aufgabenstau über Nacht zu verhindern und die Ladezeiten nicht durch Hintergrundaufgaben negativ zu beeinflussen, richten wir meist trotzdem einen serverseitigen Cronjob ein.

Tipp: Um einen Überblick über alle Aufgaben und Zeitpläne zu bekommen, die im WP-Cron hinterlegt sind, können wir das kostenlose Plugin WP Crontrol empfehlen.

Von Datenstruktur bis Abgleich: so kommt alles zusammen

Wie wir gesehen haben, besteht der Prozess zur Synchronisierung von Daten von einem API-Endpunkt in eine WordPress-Website aus mehreren Schritten. Die Grundlagen sind das Herstellen einer Verbindung zu einem Endpunkt und das Verständnis der Datenstruktur, die er bereitstellt. Sobald wir die Datenstruktur verstanden haben, können wir mit der Zuordnung der Daten zu den korrespondierenden Feldern in einem Custom Post Type beginnen. Dies kann entweder individuell programmiert werden oder, wie bei uns, durch eine Software mit Benutzeroberfläche (unser internes API-Import-Plugin) erleichtert werden.

Der eigentliche Datenimport beinhaltet das Abrufen der Daten von der API, das Verarbeiten der Daten gemäß ihrem Format (JSON oder XML) und dann das Befüllen der WordPress Post Types mit diesen Daten. Dieser Prozess sollte robust genug entwickelt werden, um auch große Datenmengen ohne Leistungsprobleme verarbeiten zu können.

Die meisten Daten-Synchronisierungen sind jedoch keine einmalige Aufgabe. API-Endpunkt müssen meist regelmäßig abgefragt werden und der Abgleich der schon gespeicherten mit den neuen Daten sollte dafür sorgen, dass der Datenbestand am Ende auf beiden Seiten der Schnittstelle übereinstimmt.

Da die Synchronisierung von Daten aus einer externen Quelle keine ganz triviale Angelegenheit ist, ist es hilfreich, den Prozess zu protokollieren. Für unser API-Import-Plugin haben wir ein eigenes, maßgeschneidertes Protokollierungssystem entwickelt, um jederzeit genau nachvollziehen zu können, was unser Plugin tut. Es gibt hier mehrere Ebenen: Einige Statusaktualisierungen sind rein informativ, andere beinhalten jedoch Warnungen, Fehler und Debug-Nachrichten.

Beispiel für das Logging von API-Daten

Neben der Analyse der genauen Verarbeitungsabläufe im WordPress-Plugin, können so auch Probleme auf der anderen Seite der Schnittstelle, also dem externen API-Endpoint, schnell aufgedeckt und behoben werden.

Wir hoffen, Sie haben einen kleinen Einblick in das Thema API-Synchronisierung für WordPress gewinnen können. Sprechen Sie uns gerne an, falls Sie Fragen haben oder wir Sie bei der Entwicklung einer eigenen API-Anbindung unterstützen können.