Die Bedeutung von fachspezifischen REST-APIs

von Bernd Hort,
assono GmbH, Standort Hamburg,

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.

Nächste Artikel in dieser Reihe:

Fachbeitrag IBM Domino Web-Entwicklung

Sie haben Fragen zu diesem Artikel? Kontaktieren Sie uns gerne: blog@assono.de

Sie wollen eine individuelle Lösung? Kontaktieren Sie uns

Weitere interessante Artikel

Sie haben Fragen? Wir sind für Sie da.

Wenn Sie mehr über unsere Angebote erfahren möchten, können Sie uns jederzeit kontaktieren. Sie können uns auf verschiedene Weisen für eine unverbindliche Erstberatung erreichen:

assono GmbH

Standort Kiel (Zentrale)
assono GmbH
Lise-Meitner-Straße 1–7
24223 Schwentinental

Standort Hamburg
assono GmbH
Bornkampsweg 58
22761 Hamburg

Telefonnummern:
Zentrale: +49 4307 900 407
Techn. Hotline: +49 4307 900 403
Vertrieb: +49 4307 900 402

E-Mail-Adressen:
kontakt@assono.de
bewerbung@assono.de