REST-Schnittstelle im Anwendungsentwurf

Eine REST-Schnittstelle stellt die Daten einer Anwendung als benannte Objekte unter festen Adressen bereit, die mit den Verben des Web-Protokolls gelesen und verändert werden. Der Entwurf entscheidet über die Haltbarkeit: Wer den Schnitt der Objekte falsch legt, baut jede spätere Erweiterung gegen den eigenen Aufbau.

REST-Schnittstelle: Datenobjekte hinter festen Adressen

REST beschreibt keinen Standard mit Prüfsiegel, sondern einen Baustil. Sein Kern: Jede fachliche Sache — Auftrag, Kunde, Beleg — bekommt eine eigene Adresse, und diese Adresse bleibt gleich, unabhängig davon, was mit ihr geschehen soll. Statt /getAuftrag?id=17 steht dort /auftraege/17; ob gelesen oder geändert wird, sagt die Methode des Aufrufs.

Der Unterschied ist kein Geschmack. Sobald Vorgänge als Adressen benannt sind, lassen sich Zwischenspeicher, Zugriffsrechte und Protokolle an genau diesen Adressen festmachen. Eine Sammlung von Funktionsnamen erzwingt dagegen für jede neue Anforderung einen neuen Namen, den außerhalb des bauenden Teams niemand erraten kann.

Methoden, Statuscodes und Zustandslosigkeit

Vier Verben tragen den größten Teil der Arbeit: GET liest, POST legt neu an, PUT ersetzt einen vorhandenen Stand, DELETE entfernt ihn. Wichtig ist die Zusage dahinter: GET verändert nichts, PUT und DELETE dürfen mehrfach ausgeführt werden, ohne zusätzlichen Schaden anzurichten. Nur POST erzeugt bei jedem Aufruf etwas Neues und braucht deshalb eine mitgelieferte Kennung des Vorgangs, damit ein wiederholter Versand nicht zwei Aufträge hinterlässt.

Der Statuscode ist Teil der Antwort und nicht Beiwerk. Erfolg, fehlerhafter Aufruf, fehlende Anmeldung, fehlendes Recht, unbekanntes Objekt, Konflikt mit dem aktuellen Stand, überschrittene Aufrufgrenze und Fehler auf der Gegenseite haben jeweils einen eigenen Code. Wer alles mit Erfolg beantwortet und den Fehler in den Antworttext schreibt, zwingt jeden Aufrufer zum Raten und macht eine maschinelle Auswertung unmöglich.

Zustandslos heißt: Der Aufruf trägt alles bei sich, was zur Bearbeitung nötig ist — Anmeldung, Kennungen, Filter. Die Gegenseite merkt sich zwischen zwei Aufrufen nichts. Das klingt unbequem, macht aber erst möglich, dass mehrere Instanzen dieselbe Last tragen und ein Neustart keinen Vorgang zerreißt.

Entwurf: Schnitt, Formate, Paginierung

Vor der ersten Zeile Code steht der Schnitt einer REST-Schnittstelle: Welche Objekte gibt es, welches ist führend, welche Beziehungen werden abgebildet. Bewährt hat sich, die Sprache der Fachabteilung zu übernehmen statt der Tabellennamen der Datenbank — Tabellen ändern sich, Fachbegriffe selten.

• Formate. JSON als Regelfall, Zeitangaben mit Zeitzone, Beträge als Dezimalzahl mit eigenem Währungsfeld, Aufzählungen als feste Werte statt freier Texte.
• Filter und Sortierung. Als Angaben in der Adresse, beschrieben und begrenzt — sonst wird aus einem Filter eine Volltextsuche über die ganze Datenbank.
• Paginierung. Große Mengen werden in Seiten geliefert, mit einer Marke für die Fortsetzung statt einer laufenden Nummer; sonst verschieben sich Einträge zwischen zwei Abrufen.
• Teilantworten. Ein Feld, mit dem der Aufrufer nur die benötigten Angaben anfordert, spart Übertragung und macht spätere Erweiterungen ungefährlich.

Wie diese Festlegungen in einen Ablauf zwischen mehreren Systemen eingebettet werden, zeigt der Beitrag zur API-Integration.

Versionierung ohne Bruch für bestehende Aufrufer

Eine veröffentlichte Zusage lässt sich nicht zurücknehmen, solange jemand sie nutzt. Erweiterungen sind harmlos, solange sie zusätzlich sind: Ein neues Feld stört keinen Aufrufer, der es nicht liest. Gefährlich sind Umbenennungen, geänderte Bedeutungen und entfernte Felder — dafür gibt es eine neue Fassung unter eigener Adresse, während die alte weiterläuft und ihr Ende angekündigt wird.

Praktisch bewährt sich, die Nutzung je Fassung zu messen. Erst wenn eine alte Fassung messbar niemand mehr aufruft, wird sie abgeschaltet, nicht nach Gefühl. Das gilt im eigenen Haus genauso wie gegenüber fremden Aufrufern, denn die eigenen Anwendungen sind erfahrungsgemäß die letzten, die umgestellt werden.

REST-Schnittstelle prüfen: Testfälle und Vertragstests

Geprüft wird auf drei Ebenen, und keine ersetzt die andere. Zuerst die Regeln der Fachlogik, unabhängig vom Web-Protokoll. Dann der Aufruf selbst gegen eine laufende Instanz: richtige Statuscodes, richtige Formate, richtiges Verhalten bei fehlenden Rechten und fehlerhaften Angaben. Zuletzt der Vertragstest, der die veröffentlichte Beschreibung gegen die tatsächlichen Antworten hält und Abweichungen meldet, bevor ein Aufrufer sie bemerkt.

Dazu kommen die unbequemen Fälle, die im Betrieb den Ausschlag geben: zwei gleichzeitige Änderungen am selben Objekt, ein abgebrochener Aufruf mitten in der Verarbeitung, ein Aufrufer, der dieselbe Anlage mehrfach schickt. Erst wenn diese Fälle Testfälle sind, trägt der Zugang. Welche Prüfungen als erfüllt gelten, gehört in die Leistungsbeschreibung und ist später der Maßstab der Abnahme.

Wo Ereignis oder Datei besser passen

Nicht jeder Austausch gehört hinter einen Aufruf auf Anfrage. Muss die Gegenseite sofort erfahren, dass etwas geschehen ist, ist ein Ereignis das passende Mittel: Das Quellsystem meldet die Änderung selbst, statt dass jemand im Minutentakt nachfragt. Geht es um sehr große Mengen ohne Zeitdruck — Stammdaten einer Nacht, ein vollständiger Bestand —, ist eine Datei mit Prüfsumme sparsamer und leichter zu wiederholen.

Auch eine Warteschlange hat ihren Platz, wenn Lastspitzen auftreten oder ein Zielsystem zeitweise stillsteht. Die Wahl richtet sich nach drei Fragen: Wie zeitnah muss die Gegenseite Bescheid wissen, wie groß ist die Menge, wie zuverlässig ist die Verbindung. Beantwortet werden sie vor dem Entwurf, nicht nach der ersten Störungsmeldung.

Wir schneiden die Wege deshalb je Datenfluss und prüfen jeden einzeln gegen das Quellsystem: Richtung, Auslöser, Felder und das Verhalten im Fehlerfall stehen auf einem Blatt, bevor der erste Aufruf gebaut wird. Zu jedem Fluss gehört die Festlegung, woran eine Störung auffällt und wer sie sieht — sonst verschiebt eine Anbindung den Fehler nur vom Bildschirm ins Protokoll. Welche Arbeiten dazugehören, steht auf der Seite Integrationen.