REST, HATEOAS und saubere API-Strukturen

Viele APIs sind heute nur noch JSON-Tunnel mit HTTP-Syntax. Sie liefern Daten, aber kaum Struktur. Der Client soll selbst wissen, welche Aktionen erlaubt sind, welche Übergänge sinnvoll sind und welche Felder unter welchen Bedingungen sichtbar oder editierbar werden. Das funktioniert für einfache Systeme erstaunlich lange. Es ist aber architektonisch schwach.

Mich interessiert an REST nicht das Dogma, sondern die Form. Eine saubere API sollte dem Client mehr geben als bloße Werte. Sie sollte ihm auch etwas über Möglichkeiten sagen. Genau dort wird HATEOAS interessant, sofern man es nicht als akademisches Ritual missversteht.

Im Blogprojekt sieht man das ganz gut an der Post-Liste. Die API liefert nicht nur Zeilen. Sie ergänzt Links und damit ausdrückliche Handlungsoptionen.

for (post <- entities.asScala) {
  BlogPostLocalization.projectForView(post.data, locale)
  post.data.commentCount = post.data.comments.size()
  post.data.addLinks(
    LinkBuilder.create[BlogPostController](_.read(post.data, null))
      .build()
  )
}

Und für authentifizierte Benutzer kommen auf Tabellenebene weitere Aktionen dazu:

table.addLinks(
  LinkBuilder.create[BlogPostController](_.save(null))
    .withRel("create")
    .build(),
  LinkBuilder.create[BlogContentSyncController](_.pull())
    .withRel("content-pull")
    .build(),
  LinkBuilder.create[BlogContentSyncController](_.`import`(null))
    .withRel("content-import")
    .build()
)

Das mag auf den ersten Blick nach „mehr Aufwand“ aussehen als ein nacktes JSON-Array. In Wirklichkeit spart es Komplexität an der richtigen Stelle. Der Client muss nicht hartkodieren, ob ein neuer Beitrag erzeugt werden darf. Er kann es aus dem System lesen. Er muss nicht erraten, ob Content-Sync verfügbar ist. Er bekommt die Information als Teil der Antwort.

Das ist für mich der eigentliche Wert einer sauberen REST-Struktur: Der Server beschreibt nicht nur Zustand, sondern auch erlaubte nächste Schritte. Gerade in Systemen mit Rollen, Rechten oder variabler UI ist das enorm wertvoll.

HATEOAS wird oft verspottet, weil man darunter riesige Hypermedia-Systeme versteht. Diese Kritik ist verständlich. Viele Implementierungen waren tatsächlich überladen. Aber daraus folgt nicht, dass die Grundidee schlecht wäre. Die schlechte Idee ist nur, sie unnötig kompliziert zu machen.

In einem ruhigen System genügt oft schon etwas viel Schlichteres:

1. Das Fachobjekt trägt seine relevanten Links.
2. Die Tabelle oder Collection trägt ihre Aktionen.
3. Rollen und Berechtigungen entscheiden serverseitig, was wirklich angeboten wird.
4. Der Client reagiert auf Möglichkeiten, statt sie komplett vorauszusetzen.

Damit wird die API nicht „magisch“, sondern im Gegenteil ehrlicher. Sie gibt dem Client eine aktuelle, serverseitig verantwortete Beschreibung der Handlungsfläche.

Auch die Filterung ist ein gutes Beispiel. In der Blogliste wird serverseitig entschieden, dass Nicht-Administratoren nur veröffentlichte Beiträge sehen:

if (!currentIdentity.hasRole("Administrator")) {
  search.status = BlogPostStatus.PUBLISHED
}

Ich mag diese Art von Entscheidung in der API, weil sie an der richtigen Stelle sitzt. Es ist keine UI-Notiz. Es ist keine versteckte Filterlogik im Browser. Es ist Fachregel an der Schnittstelle.

Saubere API-Strukturen bedeuten für mich deshalb nicht nur „schöne Endpunkte“. Sie bedeuten:

1. klare Ressourcen
2. explizite Such- und Filtermodelle
3. serverseitig verantwortete Berechtigungslogik
4. Links und Aktionen als Teil der Antwortstruktur
5. möglichst wenig Raterei auf Client-Seite

Das ist auch der Grund, warum ich APIs nicht als reine Datenbankprojektion entwerfe. Die API ist kein technischer Unfall zwischen Frontend und Persistenz. Sie ist ein eigener architektonischer Raum.

Wenn sie gut gebaut ist, wird das ganze System ruhiger. Der Client muss weniger wissen. Die Fachregeln stehen sichtbarer. Und Änderungen an Rechten oder Abläufen lassen sich am Server sauberer steuern.

Für mich ist das eine deutlich bessere Form von REST als die heute weit verbreitete Variante „Hier ist JSON, viel Glück damit“.