© Dusit Panyakhom, 123RF

Internetanbieter vermarkten ihre offenen Schnittstellen oft als Restful. Doch trifft dies auf die APIs wirklich zu, zumal kein Standard existiert? Das Linux-Magazin stellt beispielhaft einige REST-Anbieter vor und schaut, wie nah ihre API-Architekturen dem REST-Prinzip kommen.

REST ist ein Designprinzip für Programmierschnittstellen. Es handelt sich weniger um einen konkreten Standard, sondern eher um eine Sammlung von Leitlinien für den Entwurf von Webschnittstellen. REST schreibt sich auf die Fahnen, Hypermedia konsequent zu nutzen, um einen Webservice maximal zu skalieren und so flexibel wie möglich zu gestalten. Dem theoretischen Überbau zu REST widmete bereits das Linux-Magazin 06/17 einen längeren Beitrag [1].

Wer das Prinzip erst einmal erlernt hat, dem fällt das Einarbeiten in neue REST-Schnittstellen leichter. Anbieter profitieren von REST, wenn sie offene Schnittstellen möglichst rasch verbreiten und so für viele Entwickler attraktiv machen wollen.

Allerdings erfordert ein Restful-API zugleich Disziplin beim Entwurf, was einige Anbieter dazu veranlasst, eine Abkürzung über proprietäre Formate und Funktionsaufrufe zu nehmen. Denn das Einbinden von Standards braucht Zeit und nicht jeder Entwickler und jedes Unternehmen brechen in lauten Jubel aus, wenn sie die Dokumentation ergänzen oder zusätzliche Abstraktionsschritte einbauen müssen.

Das gilt erst recht, wenn eine Anwendung komplexer wird: Der Entwickler muss dann mehr Aufwand betreiben, um jeden relevanten Anwendungszustand über eindeutige URLs zu repräsentieren.

Auf die Plätze!

Um im Folgenden nicht Äpfel mit Birnen zu vergleichen, stellt der Artikel noch einmal kurz die zentralen Begriffe eines Restful-API vor.

Dreh- und Angelpunkt ist die Ressource. Das kann eine Datei sein, ein Datenbankeintrag, aber auch ein bestimmter Anwendungszustand oder ein Zwischenschritt im Programmablauf. Diese Ressource reicht der Entwickler niemals direkt an die Schnittstelle durch, sondern greift zu einer verallgemeinerten Darstellung, die sie repräsentiert.

Dieser indirekte Weg über die Repräsentation ist ein weiteres wichtiges Element von REST. Das Rails-Framework oder die objektorientierte Programmierung (OOP) verkörpern dieses Prinzip. Auch sie ziehen eine zusätzliche Darstellungsschicht ein, um Nutzersicht und Anwendungslogik sauber zu trennen. Aus einem Datenbankeintrag macht Rails ein Modell oder die objektorientierte Programmierung ein Objekt (OOP), das sich an der Anwendungslogik orientiert und weniger am Datenbankschema.

Hypermedia kombiniert Hypertext und Multimedia miteinander. REST nutzt Hyperlinks, um Dokumente miteinander zu verknüpfen. Das erlaubt eine Navigation entlang eines vorgesehenen Ablaufs. Hypermedia erlaubt es also, Ressourcen auf eine Weise zu verknüpfen, bei der sich der nächste Schritt aus den vorliegenden Informationen ergibt. Dies definiert zugleich ein viertes Kriterium für ein Restful-API: Das darauf basierende Protokoll sollte selbsterklärend sein.

Fertig machen!

Die Begriffsfindung deutet schon an, dass es einigen Spielraum für das Anlegen eines Restful-API gibt. Weil einheitliche Standards für REST fehlen, zieht der Artikel die in [1] vorgestellten Entwurfskriterien heran:

• Eindeutige Uniform Resource Identifier (URI) adressieren Ressourcen wie Datenbankeinträge und die für den Ablauf relevanten Anwendungszustände.
• Der Entwickler manipuliert Ressourcen nicht direkt, sondern verwendet eine Darstellungsschicht, die der Nutzersicht entgegenkommt.
• Der Datenaustausch basiert auf Hypermedia und der interaktiven Verknüpfung der Anwendungsschritte.
• Der nächste Anwendungsschritt lässt sich aus den aktuell vorliegenden Informationen antizipieren.

Ein Restful-API, das den Namen verdient, sollte die vier Kriterien umsetzen, wobei sie allein noch keine Qualitätsgarantien bieten. Auch proprietäre RPC-Schnittstellen über HTTP skalieren gut und sind einfach zu nutzen, doch sollte nicht Restful draufstehen, wo kein REST drin ist.

Los!

Aus der Liste von Anbietern, die ihre APIs “Restful” nennen, pickt sich der Artikel im Folgenden drei stellvertretend heraus. Zwei – die von Twitter [2] und WordPress [3] – sind bekannte Internetdienste. Aufgrund der hohen Nutzerzahlen und offenen Schnittstellen lässt sich bei ihnen eine Affinität zu REST erwarten. Ein kleinerer Anbieter (Figo, [4]) will mit REST Onlinebanking-Schnittstellen von Banken abbilden.

Der Artikel stellt die APIs der Dienste vor und bewertet ihre “Restfulness” nach den genannten Kriterien mit einem Score von 1 bis 3 pro Kriterium (Tabelle 1). Dabei signalisieren die Ziffern, wie die Anbieter das Restful-API umsetzen: 1 (spärlich), 2 (durchschnittlich) und 3 (umfassend).

Twitter

Twitter ist nach wie vor ein Webdienst für Kurznachrichten mit einer Länge von 140 Zeichen. Die lassen sich inzwischen aber um Fotos, Videos, Standortinformationen und Umfragen ergänzen, was auch den Funktionsumfang der entsprechenden Schnittstelle deutlich erweitert.

Twitter bietet mehrere APIs an, die das Entwickler-Portal gut dokumentiert [5]. Sie erlauben es, Twitter-Daten zu lesen und zu schreiben, neue Tweets zu verfassen oder Benutzerprofile und Follower-Daten auszulesen. Das Oauth-Protokoll [6] authentifiziert die API-Clients, als Datenformat kommt Json zum Einsatz. Für die Echtzeit-Überwachung von Tweets steht ein separates Streaming-API bereit.

Wer die Twitter-APIs nutzen will, muss sich und seine Anwendung zunächst auf der Twitter-Plattform [7] registrieren, um dann die Zugangs-Token zu generieren. Um eine Anwendung zu registrieren, fordert Twitter lediglich einige beschreibende Daten und die Zustimmung zu den Nutzungsbedingungen. Abbildung 1 zeigt die Konfigurationsseite der Anwendung. Die beim Anmelden erzeugten Zugangs-Token verwendet der API-Client später, um sich per Oauth als bekannt vorzustellen.

Abbildung 1: Auf diese Konfigurationsseite für eine Twitter-API-Anwendung trifft der Nutzer, wenn er sich registriert hat.

Die zahlreichen Bibliotheken unter [8] helfen dabei, einen Client zu entwickeln. Sie erleichtern es erheblich, API-Clients zu programmieren. Listing 1 zeigt zum Beispiel einen Ruby-Client auf Basis der Ruby-Bibliothek »twitter«, der sich mit einem Access-Token beim Konto des Benutzers »23Cent« authentifiziert. Anschließend lädt und zeigt der Client den Namen des Benutzers, die ID, den eindeutigen URI, das Erstellungsdatum sowie alle verfügbaren Tweets zum Konto. Die Werte für die Zugangsschlüssel und -Token finden sich in der Anwendungskonfiguration unter »Keys and Access Tokens«.

01 require 'twitter'
02
03 client = Twitter::REST::Client.new do |config|
04   config.consumer_key        = "YOUR_CONSUMER_KEY"
05   config.consumer_secret     = "YOUR_CONSUMER_SECRET"
06   config.access_token        = "YOUR_ACCESS_TOKEN"
07   config.access_token_secret = "YOUR_ACCESS_SECRET"
08 end
09
10 user = client.user("23Cent")
11 puts user.name
12
13 def collect_with_max_id(collection=[], max_id=nil, &block)
14   response = yield(max_id)
15   collection += response
16   response.empty? ? collection.flatten : collect_with_max_id(collection, response.last.id - 1, &block)
17 end
18
19 def client.get_all_tweets(user)
20   collect_with_max_id do |max_id|
21     options = {count: 200, include_rts: true}
22     options[:max_id] = max_id unless max_id.nil?
23     user_timeline(user, options)
24   end
25 end
26
27 tweets = client.get_all_tweets("23Cent")
28
29 tweets.each do |t|
30   puts t.id, t.uri, t.created_at
31   puts t.full_text
32 end

Eine Bibliothek verdeckt in diesem Beispiel jedoch die API-Aufrufe, indem sie eine eigene Logik darüberlegt. Ob das API ursprünglich Restful war, lässt sich so kaum beurteilen. Hilfe naht in Form des Ruby-Skripts Twurl [9]. Es ahmt den Webcrawler Curl nach und operiert beinahe direkt mit den API-Aufrufen. Die Dokumentation [5] verrät, dass das API die HTTP-Methoden »GET«, »POST« und »DELETE« unterstützt.

Um die erste Aufgabe des Programms in Listing 1 zu erledigen und den Namen des Benutzers (»users«) auszugeben (über »show«), bietet sich die Methode »GET« an. Hierfür schlägt die Dokumentation die Resource-URL https://api.twitter.com/1.1/users/show.json vor. Eine entsprechende Authentifizierung mittels Oauth vorausgesetzt, liefert ein »GET« auf diese URL mit dem passenden Twitter-Alias (»screen_name«, hier »23Cent«) ausführliche Informationen zum Benutzer:

GET https://api.twitter.com/1.1/users/show.json?screen_name=23Cent

Listing 2 zeigt einen kleinen Auszug aus der Antwort im Json-Format.

01 [...]
02 {
03         "id":16590222,
04         "id_str":"16590222",
05         "name": "Marcus Nasarek",
06         "screen_name":"23Cent",
07         "location":"Berlin, Deutschland",
08         "url":"http://marcus-nasarek.de"
09         [...]
10 }
11 [...]

Das Twitter-API erschließt sich also recht intuitiv. Die Ressourcen und Anwendungszustände adressieren Entwickler weitgehend über eindeutige URIs und die Antworten auf Methodenaufrufe (»GET«, »POST« und »DELETE«) liefern genügend Hinweise auf die nächsten Anwendungsschritte.

Twitter liefert in den Json-Antworten zudem zahlreiche URLs, die es erlauben, weitere Ressourcen zu adressieren. Json selbst [10] ist kein Hypermedia-Format, die Entwickler erweitern es über diverse Json-Schemes einigermaßen. Twitter nutzt ein eigenes Schema, das auch Multimedia-fähig ist. Aus Sicht eines Restful-API ist dies sicher ein pragmatischer und nachvollziehbarer Weg, vollständig “Restful” ist er aber nicht.

Dass Twitter Daten wiederverwendet und kontextbezogene kombiniert, lässt darauf schließen, dass der Dienst die Darstellungsschicht sauber trennt. Insgesamt bewegt sich Twitters REST-API tatsächlich nah am Ideal eines Restful-API.

WordPress

WordPress ist eine Open-Source-Anwendung für Blogs. Nutzer installieren es auf ihrem eigenen Webserver oder nutzen es als vorkonfigurierten Webservice [3]. Neben verschiedenen anderen APIs steht auch ein gut dokumentiertes [11] REST-API bereit. Das verwendet ebenfalls Json, die Hypermedia-Fähigkeit orientiert sich am HAL-Standard [12].

Der Artikel betrachtet das API des Webdienstes WordPress.com, das der Dienst deutlich aufgewertet hat. Clients authentifizieren sich auf Basis von Oauth2. Die entsprechenden Zugangs-Token erhalten Entwickler, indem sie ihre Clientanwendung unter [13] registrieren.

WordPress.com bringt zugleich eine praktische Sandbox mit, die »Wordpress.com Console«, die es Entwicklern erlaubt, sich mit dem API vertraut zu machen (Abbildung 2). WordPress.com bietet außerdem eine ausführliche Dokumentation des REST-API an.

Abbildung 2: WordPress.com stellte eine Sandbox für erste Experimente mit dem REST-API zur Verfügung.

Beim Einarbeiten mit Hilfe der Sandbox fällt zunächst jedoch auf, dass das Löschen einer Ressource nicht über die HTTP-Methode »DELETE« erfolgt, stattdessen nutzt WordPress »POST«-Aufrufe dafür. Das ist verständlich, da WordPress auf möglichst vielen Servern laufen will und nicht alle sämtliche HTTP-Methoden unterstützen. Vermutlich geht der Anbieter auf Nummer sicher und bietet nur die gängigsten Methoden an.

Der Nutzer fragt diesmal alle Blogeinträge eines Nutzers ab, die zurückgelieferte API-Antwort im Json-Format zeigt auszugsweise Listing 3. Die Antwort enthält sehr ausführliche Informationen mit zahlreichen Verweisen auf weitere Ressourcen mit den entsprechenden URIs, wo es nötig ist. Dank der ausführlichen Metadaten erschließen sich auch schnell mögliche weitere Schritte – durch entsprechende Hinweise auf die Berechtigungen – sowie die notwendigen IDs für den Aufruf anderer Ressourcen.

01 [...]
02 {
03         "sites": [
04                 {
05                     "ID": 20267300,
06                     "name": "Raspberry Pi Lab",
07                     "description": "Code AMBER",
08                     "URL": "http://raspilab.blog",
09                     "user_can_manage": false,
10                     [...]
11
12 }
13 [...]

Das WordPress.com-API erleichtert also eine intuitive Nutzung. Auch gelingt es damit, Ressourcen und Anwendungszustände weitgehend über eindeutige URIs zu adressieren.

Das trifft aber nicht für jeden einzelnen Anwendungsschritt zu. Die Antworten auf Abfragen und übermittelte Daten sind sehr ausführlich und liefern viele Hinweise auf die nächsten Anwendungsschritte. Allerdings braucht ein Entwickler einige Einarbeitungszeit, um die WordPress-spezifischen Abläufe und deren Logik zu erfassen.

Mit Hilfe der URIs und eingebetteten Multimediaformate verwandelt WordPress das verwendete Json-Format in ein Hypermedia-Format, für das es allerdings keine Standards verwendet. Der konkrete Aufbau der Daten erschließt sich erst nach einem sorgfältigen Studium der Dokumentation. So erfordert die Übermittlung eines neuen Beitrags mit einem »POST« auf »/sites/$site/posts/new« ein recht komplexes Datenkonstrukt.

An dieser Stelle packt das REST-API also verschiedene Formate und Ressourcen in einem Json-Format zusammen und versucht einen Spagat zwischen möglichst wenig Ressourcen-URLs und viel Funktionalität. Das erscheint jedoch als Bruch mit der reinen Lehre.

Figo

Als Vertreter aus dem deutschsprachigen Raum kommt Figo ins Spiel, das Webservices für Banken anbietet [4]. Über das REST-API des Anbieters greifen andere Dienste auf die Konten von Tausenden Banken zu – natürlich mit Autorisierung der Konteninhaber. Jüngste Gesetzesänderungen haben einen Rechtsrahmen dafür geschaffen, solche Dienste europaweit anzubieten.

Aus Sicht eines REST-API und mit Blick auf die traditionellen Banking-Schnittstellen erscheint die Verknüpfung dieser Welten als Herausforderung. Die meisten Banken in Deutschland unterstützen eine offene Schnittstelle namens Fin TS [14], deren geistige Ursprünge bis zum BTX-Banking zurückreichen – angekündigt auf der Cebit 1983. Das Neuland von damals scheint heute etwas angestaubt: Zwar verwendet Fin TS vorbildlich das XML-Format und damit ein Hypermedia-Format, doch verpackt dieses die klassischen Nachrichten lediglich neu.

Das Figo-API setzt das Fin-TS-Format oder alternativ die Onlinebanking-Webseite einer Bank in einer REST-Logik um. Will der Entwickler darauf zugreifen, muss er sich für den Zugriff auf das API und die Testumgebung per E-Mail registrieren. Als Antwort flattern eine Client-ID, das Oauth-Secret sowie die Zugangsdaten zum Demo-Account ins Haus.

Die Dokumentation des API und die Lehrmittel für Entwickler sind erfreulich umfangreich [15]. Neben einem Demokonto gibt es auf Github [16] SDKs für die wichtigsten Skriptsprachen und entsprechende Beispielprogramme, die Figo ebenfalls gut dokumentiert. Zudem hält es sich sehr genau an API-Konventionen, sodass sich die Aufrufe nach dem Studium des API intuitiv erschließen. Die API-Spezifikation selbst gibt es im Textformat und als Open-API-2.0-konforme Json-Datei. Die erlaubt es, sie in Swagger-IDEs einzulesen.

01 require "figo"
02
03 session = Figo::Session.new("ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ")
04
05 # Ausgabe der Kontonummer und des Saldos
06 session.accounts.each do |account|
07   print "ID: #{account.account_id}"
08   print " | KNR: #{account.account_number}"
09   puts " | SALDO: EUR #{account.balance.balance}"
10 end
11
12 # Ausgabe aller Transaktionen und einiger Transaktionsdetails
13 puts "Die letzten 10 Umsätze für Konto mit ID A1.1:"
14 session.get_account("A1.1").transactions[-11..-1].each do |transaction|
15   print "#{transaction.name}"
16   d = Date.strptime("#{transaction.value_date}", '%FT%T%:z')
17   print " | #{d.strftime("%a, %d.%b %Y")}"
18   print " | #{transaction.amount}"
19   puts " | #{transaction.purpose[0..20]}"
20 end

Listing 4 zeigt ein kleines Ruby-Skript, das auf das Demokonto des Figo-Servers zugreift. Die Ausgabe stellt Listing 5 dar. Es zeigt, wie der Entwickler mit wenigen Programmzeilen Kontodaten abruft. Das Demokonto fungiert hierbei als so genannter Aggregationsdienst, die Kontodaten landen zwischenzeitlich auf den Figo-Servern. So kann ein Dienst theoretisch die Kontodaten mehrerer Banken sammeln und zentral zur Verfügung stellen. Alternativ erfolgt ein Kontoabruf direkt auf dem jeweiligen Bankkonto. Dafür muss der Benutzer aber stets die Kontozugangsdaten neu eingeben. Für beide Varianten stehen SDKs bereit.

01 $ ruby figo_demo.rb
02 ID: A1.1 | KNR: 4711951500 | SALDO: EUR 3250.31
03 ID: A1.2 | KNR: 4711951501 | SALDO: EUR 2190.42
04 ID: A1.4 | KNR: 4711951502 | SALDO: EUR 11754.65
05 Die letzten 10 Umsätze für Konto mit ID A1.1:
06 Kanne Brottrunk Gmbh & Co. Kg | Tue, 06.Aug 2013 | -50.1 | Rechnung-Nr. 98421312
07 Blumen Meier | Wed, 07.Aug 2013 | -18.2 | Rg. Nr. 2013/312 100
08 Schnitzelei | Thu, 08.Aug 2013 | -230.0 | Ec 8233123 0707123388
09 Bitstream, Inc. Myfonts | Fri, 09.Aug 2013 | -29.9 | Usa Marlborough Usd 2
10 Berliner Verkehrsbetriebe | Sat, 10.Aug 2013 | -57.92 | Konto Bei Uns 0001423
11 Techniker Krankenkasse | Sun, 11.Aug 2013 | -230.0 | Versichertennr 123197
12 Dr. House Solutions Gmbh | Mon, 12.Aug 2013 | -1753.2 | Miete Juli 2012
13 Airfreu Ag | Tue, 13.Aug 2013 | 2300.0 | Gehalt
14 Christoffel Blindenmission | Wed, 14.Aug 2013 | -30.0 | Elv14ß0890843 06.07 1
15 Ga Nr00021288 Blz20020000 2 | Thu, 15.Aug 2013 | -100.0 | 18.07/09.57Uhr Rathau
16 Ihr Blumenversand | Fri, 16.Aug 2013 | -24.99 | Rg. 2312, 12.02.2013

Das Figo-API adressiert also alle Ressourcen über eindeutige URIs und ist zudem mustergültig dokumentiert. Wie intuitiv sich die Nutzung des API aus den vorliegenden Informationen erschließt, hängt allerdings auch davon ab, wie gut die Entwickler den zugrundeliegenden Zahlungsverkehr kennen. Ablaufdiagramme in der Dokumentation helfen dabei, den Ablauf eines klassischen Kunde-Bank-Dialogs zu verstehen.

Als Datenaustauschformat setzt Figo auf eine eigene Json-Spezifikation. Augenscheinlich hat das Format wenig mit Hypermedia zu tun. Allerdings spricht das API mit einer Tabellenlogik auf der Bankenseite, die nicht selten noch auf Mainframes gehostet wird. Jeder Daten- oder Transaktionszugriff ist daher ein abgeschlossener Geschäftsvorfall, um in der Fin-TS-Sprache zu sprechen.

Die Ablaufdiagramme deuten an, dass einige der Einzelschritte zusammenhängen und bestimmte weitere Ressourcen mit ihnen verknüpft sind. Es würde Sinn ergeben, URIs und Auszeichner in die API-Antwort zu integrieren. Die könnten, anders als die Wertetabellen in Textform, auf die logisch nächsten Schritten oder relevanten Ressourcen verweisen. Auszeichnungen wie »image« oder »media« wie sie HTML 5 vorsieht, helfen Entwicklern generell dabei, die Parameter in den Antworten auch maschinenlesbar einzuordnen.

Mit Blick auf die Bankenschnittstellen nutzt das Figo-API in jedem Fall eine eigene Darstellungsschicht, um die Nutzersicht zu vereinfachen. Vor diesem Hintergrund kommt auch dieses API dem Idealzustand eines Restful-API recht nahe.

Fazit

Die drei vorgestellten APIs halten sich verhältnismäßig streng an das REST-Prinzip. Zugleich verwenden alle drei mit Json kein wirkliches Hypermedia-Format, sondern gehen mit einer eigenen Json-Spezifikation pragmatisch vor. Formal fallen sie so durch den REST-Check.

Die Funktionsweise des Hypermedia-Formats lässt sich aber auch in Json nachahmen, was Twitter besser gelingt als WordPress.com. Figo bleibt zu sehr bei schlichten Wertetabellen, um die Möglichkeiten von Hypermedia konsequent zu nutzen. Die in der Dokumentation gezeigten Abläufe mit ihren Verzweigungen ließen sich gut in einem Hypermedia-Format abbilden, hier bleibt das API hinter seinen Möglichkeiten zurück.

Alle drei schaffen es aber ohne Schwierigkeiten, die Daten in einer Anwendungs- und Nutzer-orientierten Darstellungsschicht zu abstrahieren. Dies wirkt sich positiv auf die Versionspflege aus, ist also im eigenen Interesse der Anbieter. Bei Twitter und Figo zeigt sich auch der Nutzeraspekt besonders deutlich.

Was den selbsterklärenden Ablauf angeht, hat es Figo etwas schwerer, weil es an den Mechanismen des Zahlungsverkehrs und des Kunde-Bank-Dialogs hängt, löst das Problem aber im Rahmen seiner Möglichkeiten vorbildlich.

Zusammenfassend lässt sich für alle drei hier vorgestellten APIs feststellen, dass sie das Prinzip Restful zumindest für drei von vier Kriterien gut verstehen und umsetzen. Vor dem Hintergrund voranschreitender Entwicklungen im Bereich künstlicher Intelligenz wäre es aber sicherlich wünschenswert, auch Hypermedia konsequenter einzubinden.

Denn dadurch erlaubt es ein API, intuitiv entlang eines gewünschten Ablaufs von einer Ressource zur anderen zu navigieren. Zugleich kennzeichnet es Multimedia-Ressourcen deutlich als solche. Das erleichtert die Lesbarkeit des Codes für Maschinen und damit eine weitgehend automatisierte Integration.