Ratgeber · Schnittstellen

REST, JSON:API, GraphQL, gRPC oder SOAP? Schnittstellen im Vergleich

Kurz gesagt

Für die meisten Vorhaben ist REST die richtige Wahl. GraphQL lohnt sich, wenn ein Frontend sehr unterschiedliche Daten braucht. JSON:API spart Eigenbau, wo das System es schon mitbringt. gRPC ist etwas für schnelle Verbindungen zwischen Diensten, SOAP begegnet dir bei älteren Systemen in Verwaltung, Handwerk und Industrie. Entscheidend ist weniger die Technik als eine gute Dokumentation.

Grundlagen

Wofür Schnittstellen da sind

Eine Schnittstelle, oft API genannt, lässt zwei Systeme miteinander reden, ohne dass jemand Daten von Hand überträgt. Die Website holt Termine aus der Mitgliederverwaltung, das Spendenformular schickt Spenden an die Fundraising-Software, der Shop meldet Bestellungen an die Kasse.

Welche Art von Schnittstelle passt, hängt davon ab, wer sie nutzt und wie die Daten aussehen.

REST

Der Standard

REST arbeitet mit Adressen für Dinge (/termine, /termine/42) und den bekannten HTTP-Methoden zum Lesen, Anlegen, Ändern und Löschen. Fast jede Programmiersprache und fast jedes Werkzeug kann damit umgehen.

Stark: einfach, verbreitet, gut zu cachen und zu testen
Grenzen: ein Frontend braucht oft mehrere Anfragen pro Seite und bekommt mehr Daten als nötig

JSON:API

Konventionen statt Eigenbau

JSON:API ist ein festgelegtes Format für REST-Schnittstellen: Wie Beziehungen, Filter und seitenweise Ausgabe aussehen, ist vorgegeben. Drupal bringt JSON:API im Kern mit. So entsteht eine vollständige Schnittstelle zu allen Inhalten, ohne dass jemand sie von Grund auf entwickeln muss.

Stark: schnell verfügbar, einheitlich, weniger Abstimmung zwischen Teams
Grenzen: ausführliche Antworten; für sehr spezielle Abfragen braucht es trotzdem eigene Endpunkte

GraphQL

Das Frontend fragt, was es braucht

Bei GraphQL beschreibt das Frontend in einer Abfrage genau, welche Felder es haben will, auch über mehrere verknüpfte Inhalte hinweg. Beim Relaunch von dnr.de holt das React-Frontend seine Inhalte so per GraphQL aus Drupal.

Stark: eine Anfrage pro Seite, genau die nötigen Daten, ein klares Schema
Grenzen: Caching und Rechteprüfung aufwendiger als bei REST; für einfache Anbindungen oft zu viel

gRPC

Schnell zwischen Diensten

gRPC verbindet Dienste über ein kompaktes Binärformat und fest definierte Verträge. Das ist schnell und typsicher, eignet sich aber vor allem für die Kommunikation zwischen Backend-Diensten. Im Browser kommt es nur mit Zusatzaufwand an.

Stark: Geschwindigkeit, klare Verträge, gut für viele kleine Dienste
Grenzen: schlecht lesbar beim Testen, kaum Unterstützung im Browser

SOAP

Alt, aber noch überall

SOAP ist der ältere Standard mit XML und einer formalen Beschreibung der Schnittstelle (WSDL). Neue Projekte setzen selten darauf, aber viele bestehende Systeme sprechen nur SOAP. Für die Kfz-Innung Dresden kommen Mitglieder, Weiterbildungen und Stellenausschreibungen per SOAP aus den internen Systemen auf die Website.

Stark: streng beschrieben, in Unternehmenssoftware verbreitet
Grenzen: schwerfällig, viel XML, wenig moderne Werkzeuge

Entscheidungshilfe

Was passt zu deinem Vorhaben?

Situation	Unsere Empfehlung
Öffentliche Schnittstelle für Partner	REST mit OpenAPI-Dokumentation
Drupal-Inhalte für ein eigenes Frontend	JSON:API oder GraphQL
Frontend mit vielen verknüpften Daten pro Seite	GraphQL
Viele interne Dienste, hoher Durchsatz	gRPC
Anbindung an ein älteres System	SOAP, so wie es das System vorgibt
Anbindung an einen Cloud-Dienst	dessen API, meist REST

Dokumentation

Ohne Dokumentation ist jede Schnittstelle schlecht

Die beste Technik nützt nichts, wenn niemand weiß, wie man sie benutzt. Für REST-Schnittstellen beschreiben wir Endpunkte, Felder und Fehler mit der OpenAPI-Spezifikation, bei GraphQL ist das Schema die Dokumentation.

Dazu gehören Beispiele, eine Testumgebung und eine Versionierung, damit Änderungen bestehende Anbindungen nicht brechen.

Erstgespräch anfragen Mehr zu Schnittstellen