Zwei Ansätze für die Definition von REST-APIs: fachspezifisch oder datenzentriert
Ein wesentlicher Bestandteil einer jeden modernen Web-Anwendung ist die Verbindung des Frontends im Browser mit dem Backend auf Server-Seite mittels einer REST-API. Bei der Definition der REST-API gibt es zwei Ansätze: fachspezifische oder datenzentrierte REST-APIs.
Datenzentrierte REST-APIs
Die datenzentrierten REST-APIs bilden 1:1 die internen Datenstrukturen ab. Sie sind dadurch leichter zu implementieren. Ein Beispiel stellen die IBM Domino Access Data Services dar. Alle Felder eines Notes Dokumentes werden direkt als JSON ausgegeben. Hier ein Beispiel aus der Dokumentation:
{
"LastName":"Doe",
"Body": {
"content": [
{
"contentType":"multipart\/alternative; Boundary=\"0__=0ABBF337DFDA85C48f9e8a93df938690918c0ABBF337DFDA85C4\"",
"contentDisposition":"inline"
},
{
"contentType":"text\/plain; charset=US-ASCII",
"boundary":"--0__=0ABBF337DFDA85C48f9e8a93df938690918c0ABBF337DFDA85C4",
"data":"Mostly sales. Some marketing."
},
{
"contentType":"text\/html; charset=US-ASCII",
"boundary":"--0__=0ABBF337DFDA85C48f9e8a93df938690918c0ABBF337DFDA85C4",
"data":"<html><body><font size=\"2\" face=\"sans-serif\">Mostly <\/font><font size=\"2\" face=\"sans-serif\"><b>sales<\/b><\/font><font size=\"2\" face=\"sans-serif\">. Some <\/font><font size=\"2\" face=\"sans-serif\"><i>marketing<\/i><\/font><font size=\"2\" face=\"sans-serif\">.<\/font><\/body><\/html>",
"contentDisposition":"inline"
}
],
"type":"multipart"
},
"@form":"Contact",
"@created":"2011-06-29T15:30:34Z",
"@authors": [
"Anonymous",
"CN=rperronadmin\/O=rtest"
],
"@modified":"2011-08-21T15:21:51Z",
"Number":4.4,
"@href":"\/XPagesExt.nsf\/api\/data\/documents\/unid\/5BCE1CAEEBA4F309852578BE0055327B",
"City":"Trenton",
"@noteid":"922",
"Date": [
"2011-07-21T20:21:00Z",
"2011-08-01T14:38:00Z"
],
"@unid":"5BCE1CAEEBA4F309852578BE0055327B",
"FirstName":"John",
"EMail":"jdoe@acme.com"
}Die internen Feldnamen werden direkt als Eigenschaftsbezeichnungen verwendet. Viele interne Felder wie @noteid, @unid, @created usw. werden ebenfalls ausgegeben. (Was zum Teil durch Abfrageparameter ausgeschaltet werden kann.)
Fachspezifische REST-APIs
Bei fachspezifischen REST-APIs wird die REST-API anhand der Anforderungen der Anwendung modelliert. Hier ein Beispiel einer fachspezifischen REST-API:
{
"customer":"ACME Corporation",
"contactperson": {
"firstname":"John",
"lastname":"Doe",
"email":"jdoe@acme.com"
},
"deliveryaddress":{
"street":"Elmstreet",
"zip":"12345",
"city":"Somewhere"
},
"postaddress": {
"street":"Mainstreet",
"zip":"67890",
"city":"Elsewhere"
}
}Die Vorteile von fachspezifischen REST-APIs
Einer der Vorteile von fachspezifischen REST-APIs ist die besser Darstellung von Beziehungen innerhalb der Daten. In dem obigen Beispiel ist dieses gut an den Adressen erkennbar. Außerdem können Daten aus verschiedenen Quellen gemischt werden. Diese Quellen können Notes-Dokumente, ERP-System und relationale Datenbanksystem sein. Nach Außen ist die Herkunft der Daten nicht erkennbar.
Der wichtigste Vorteil ist aber Flexibilität: Mit der Veröffentlichung der REST-API wird eine Art Vertrag eingegangen. Die Nutzer der REST-API erwarten, dass die Schnittstelle stabil bleibt. Bei datenzentrierten REST-APIs gibt es keine Möglichkeit die interne Struktur der Daten zu ändern, weil jede Anpassung zu einer Änderung der Schnittstelle und somit zum "Vertragsbruch" führen würde. Selbst wenn den Entwicklern des Backends eine geniale Methode zur Performance-Verbesserung einfallen würde, könnten sie die Methode nicht einsetzen, wenn dadurch sich die REST-API ändert.
Die fachspezifische REST-API kapselt die interne Datenhaltung von der nach außen sichtbaren Schnittstelle ab. Jegliche interne Verbesserung ist so lange unbedenklich, wie die fachspezifische REST-API gleich bleibt. Gerade weil bei der Definition nur fachliche Gründe eine Rolle spielen, sollte es auch nur fachliche Gründe geben, die REST-API anzupassen.
Die Flexibilität betrifft auch noch eine andere Ebene. Sollte es irgendwelche Gründe geben, das Backend auszutauschen, kann bei der Verwendung einer fachspezifischen REST-API das Frontend unverändert weiter verwendet werden. Das neue Backend muss lediglich die gleiche fachspezifische REST-API wieder zur Verfügung stellen.
