Entwicklung einer neuen onOffice API

Schon seit vielen Jahren setzen wir eine API / Schnittstelle für verschiedene Dienste ein und stellen sie Kunden zur Verfügung, damit externe Webseiten oder extern entwickelte Tools mit unserer CRM-Software interagieren können.

Unsere Benutzeroberflächen wollen wir in Zukunft mit vue.js umsetzen und in diesem Schritt auch bei unserem eigenen CRM intensiver mit einer API arbeiten – wir verfolgen somit einen API-First-Ansatz. Auch wenn wir im ersten Schritt diese neue API nur intern einsetzen wollen, ist das Ziel auf Dauer eine API für unsere Kunden sowie externe Entwicklungen zur Verfügung zu stellen.

Neue Wege für die API

Wie immer, wenn wir Veränderungen dieser Größenordnung anstoßen, haben wir im Entwicklungsteam gefragt, wer an Recherche und Diskussionen teilnehmen möchte. Dass wir nicht weiter auf unserer bisherigen API aufsetzen wollen, war recht schnell klar, die aktuelle API kann man als proprietäres System bezeichnen. Wir haben einen hohen Aufwand zur Dokumentation und der Einsatz von gängigen Tools, um die API anzusprechen oder gar Schnittstellenbeschreibungen automatisiert abfragen zu können ist mehr oder weniger nicht möglich. 

Vor der Recherche und dem Test von bestehenden API-Technologien haben wir eine Liste von Anforderungen und Kriterien erstellt, auf die wir bei unserer neuen API Wert legen wollen. 

• Die Testbarkeit der API-Calls ist uns sehr wichtig. Auch wenn wir die API im ersten Schritt intern einsetzen werden, soll sie in Zukunft auch für Kunden und Kooperationspartner freigegeben werden. Ein Kernkriterium für eine API ist nun mal, dass es eine stabile Programmierschnittstelle ist – stabil im Sinne von: Externe Softwaretools sollten sich darauf verlassen können, dass sich die definierte Schnittstelle nicht regelmäßig ändert. Davon abgesehen, dass der Einsatz automatisierter Tests bei uns sowieso nicht mehr wegzudenken ist, ist eine durch Tests abgedeckte API nun mal stabiler.
• Um den Einsatz bestehender API-Tools zu ermöglichen und möglichst auch eine API-Dokumentation aus der API-Definition heraus generieren zu können, wollen wir auf einem bestehenden API-Standard aufsetzen.

Die Liste der Kriterien insgesamt war deutlich länger und umfasste natürlich auch Themen wie eine gute Performance (bezogen auf realistische Anwendungsfälle in unserem CRM-Umfeld),“moderne Authentifizierung oder die Möglichkeit, eingehende API-Calls und -Parameter validieren zu können.

REST vs. GraphQL

REST kann man nicht einfach ausblenden, wenn man sich mit APIs beschäftigt. Für uns haben wir REST sehr schnell als Technologie ausgeschlossen. Das Hauptargument war der oft zitierte Spruch “eine REST-API kann keinen JOIN”. Wir haben mehrere Anwendungsfälle aus unserer Domäne durchgespielt und viele davon ließen sich nur sehr schwer bzw. unschön oder mit zu erwartenden Performanceproblemen als REST-API modellieren.

Die Entscheidung ist dann auf die zweite API-Technologie, mit der wir uns länger beschäftigt haben, gefallen: GraphQL. Die Möglichkeit, mehrere Ressourcen in einer API-Abfrage zu erhalten, kombiniert mit der sehr granular steuerbaren Datenmenge pro Datensatz ist ein klarer Vorteil gegenüber dem klassischen REST-Ansatz. Mit der Möglichkeit, einzelne APIs per Schema gut beschreiben zu können (inkl. Typisierung) und der guten Unterstützung durch verfügbare Tools sindweitere Kriterien erfüllt, die uns für unsere neue API wichtig waren.

In unserem wachsenden Entwicklerteam ist es uns immer wichtig, die Skalierbarkeit von Arbeitsprozessen mit im Auge zu haben. Mit der Entscheidung, auf GraphQL zu setzen war auch hier direkt das Thema, wie möglichst effizient einzelne Entwicklerteams APIs für ihre jeweiligen Projektbereiche entwickeln und veröffentlichen können. Mit Apollo Federation steht hier ein Tool zur Verfügung, über das genau das erreicht werden kann. Einzelne Subgraphen können getrennt voneinander entwickelt und über das Apollo Federation Gateway einheitlich von außen abgefragt und sogar in einem API-Request miteinander kombiniert werden.

Der weitere Fahrplan

Um neben den ersten Spielereien mit GraphQL weitere Erfahrungen zu sammeln, haben wir ein erstes internes Testprojekt gestartet. Eine Benutzeroberfläche zur Konfiguration der von uns gehosteten Webseiten wird in vue.js umgesetzt und eine erste GraphQL-API stellt die Anbindung an die vorhandene Datenbankstruktur dar. Das Tool soll nur firmenintern eingesetzt werden. Wir haben in dem Projekt aber schon den ein oder anderen Stolperstein ausräumen können, der sonst später in größerem Projektrahmen stärker blockiert hätte. Die Apollo Federation Features stehen aktuell in PHP zum Beispiel nur mit einer kompletten Laravel-Einbindung (Lighthouse) zur Verfügung, hier haben wir im Rahmen des Testprojektes aber eine Lösung aufbauend auf graphql-php ohne Laravel-Einsatz finden können.

Sobald das Testprojekt abgeschlossen ist, wollen wir GraphQL für anstehende interne Projekte nutzen. Eine Freigabe auch für die Kunden wird (wie bei unserer bisherigen API) erst erfolgen, wenn die neue GraphQL einen entsprechenden Funktionsumfang erreicht hat.