Traverson – ein Hypermedia API Client für Node.js und den Browser

Bei vielen REST APIs sind die einzelnen Ressourcen untereinander verlinkt. Ein Client kann die Links benutzen, um von Ressource zu Ressource zu navigieren. Der Client muss nur die URI der Wurzel-Ressource kennen, von der aus alle anderen Ressourcen über Links erreichbar sind. Dies verringert die Kopplung zwischen dem API-Anbieter und den Clients. Diese Prinzip wird gemeinhin mit HATEOAS bezeichnet – Hypertext As The Engine Of Application State. REST APIs mit diesem Merkmal werden in letzter Zeit auch öfter als Hypermedia APIs bezeichnet. Wenn es nach Mr REST geht, ist dieses allerdings ohnehin ein Muss für jede REST API.

Traverson ist ein JavaScript-Modul für Node.js und für den Browser, welches das Arbeiten mit solchen APIs stark vereinfacht.

Die von GitHub zur Verfügung gestellte API (https://api.github.com/ ) ist ein Beispiel für das HATEOAS-Muster. Eine Reise von Ressource zu Ressource könnte mit dieser API folgendermaßen aussehen.

Wir beginngen mit der Wurzel-URI, https://api.github.com/, die folgendes Dokument zurückliefert:

1{
2  "current_user_url": "https://api.github.com/user",
3  "gists_url": "https://api.github.com/gists{/gist_id}",
4  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
5  ...
6}

Dann folgen wir dem Link "repository_url",
mit den Parametern { owner: "basti1302", repo: "traverson" },
und erreichen so die URI https://api.github.com/repos/basti1302/traverson

1{
2  "id": 13181035,
3  "name": "traverson",
4  "full_name": "basti1302/traverson",
5  "owner": {
6    "login": "basti1302",
7    ...
8  },
9  "url": "https://api.github.com/repos/basti1302/traverson",
10  "commits_url": "https://api.github.com/repos/basti1302/traverson/commits{/sha}",
11  "issues_url": "https://api.github.com/repos/basti1302/traverson/issues{/number}",
12  ...
13}

Dann folgen wir dem Link "commits_url",
mit dem Parameter { sha: 5c82c74583ee67eae727466179dd66c91592dd4a },
und erreichen so die URI https://api.github.com/repos/basti1302/traverson/commits/5c82c74583ee67eae727466179dd66c91592dd4a

1{
2  "sha": "5c82c74583ee67eae727466179dd66c91592dd4a",
3  "commit": {
4    "author": {
5      "name": "Bastian Krol",
6      ...
7    },
8    "committer": {
9      "name": "Bastian Krol",
10      "date": "2013-10-25T11:41:09Z",
11      ...
12    },
13    "message": "test hal support against @mikekelly's haltalk server"
14    ...
15  },
16  "url": "https://api.github.com/repos/basti1302/traverson/commits/5c82c74583ee67eae727466179dd66c91592dd4a",
17  "comments_url": "https://api.github.com/repos/basti1302/traverson/commits/5c82c74583ee67eae727466179dd66c91592dd4a/comments",
18  ...
19}

Zum Schluß folgen wir dem Link "comments_url",
und erreichen so schließlich die URI
https://api.github.com/repos/basti1302/traverson/commits/5c82c74583ee67eae727466179dd66c91592dd4a/comments

1[
2  {
3    "id": 4432531,
4    "user": {
5      "login": "basti1302",
6      ...
7    },
8    "created_at": "2013-10-25T22:50:59Z",
9    "body": "This commit is a commit is a commit.",
10    ...
11  }
12]

Wir sind also drei aufeinanderfolgenden Links gefolgt, haben uns so von Ressource zu Ressource gehangelt, um am Ende zu der Ressource zu gelangen, die uns eigentlich interessiert (die Commit-Kommentare in diesem etwas hanebüchenen Beispiel).

Traverson

Es gibt eine ganze Reihe von Bibliotheken, die den Umgang mit REST APIs vereinfachen. Die meisten davon erleichtern das Arbeiten mit einer Ressource oder einem Request. Es gibt allerdings bisher wenig Unterstützung bei dem oben skizzierten, typischen Muster, bei dem man mehreren Links folgt – zumindest nicht in der JavaScript-Welt. Hier kommt Traverson ins Spiel. Traverson macht aus dem Folgen einer Sequenz von Links einen einzelnen Methodenaufruf.

Anhand der GitHub API können wir uns anschauen, wie das in der Praxis aussieht. Wenn man den Links z. B. mit dem request -Modul für Node.js folgen wollte, könnte man folgenden Code schreiben:

1var request = require('request')
2var rootUri = 'https://api.github.com/'
3 
4function nextUri(response, link) {
5  var resource = JSON.parse(response.body)
6  return resource[link]
7}
8 
9request.get(rootUri, function(err, response) {
10  if (err) { console.log(err); return; }
11  var uri = nextUri(response, 'repository_url')
12  uri = uri.replace(/{owner}/, 'basti1302')
13  uri = uri.replace(/{repo}/, 'traverson')
14  request.get(uri, function(err, response) {
15    if (err) { console.log(err); return; }
16    uri = nextUri(response, 'commits_url')
17    uri = uri.replace(/{\/sha}/,
18        '/5c82c74583ee67eae727466179dd66c91592dd4a')
19    request.get(uri, function(err, response) {
20      if (err) { console.log(err); return; }
21      uri = nextUri(response, 'comments_url')
22      request.get(uri, function(err, response) {
23        if (err) { console.log(err); return; }
24        var resource = JSON.parse(response.body)
25        console.log(resource)
26      })
27    })
28  })
29})

Eine hübsche Callback-Pyramide, und außerdem repetetiv. Mit Traverson sieht das grundlegende Muster zum Folgen einer Kette von Links bis zur Ziel-Ressource so aus:

1var api = require('traverson').json.from('https://api.github.com/')
2api.newRequest()
3  .follow('repository_url', 'commits_url', 'comments_url')
4  .getResource(function(err, resource) {
5    // do something with the resource...
6  })

Und ein komplettes, funktionsfähiges Beispiel mit der GitHub API sieht so aus:

1var api = require('traverson').json.from('https://api.github.com/')
2api.newRequest()
3  .follow('repository_url', 'commits_url', 'comments_url')
4  .withTemplateParameters({
5    owner: 'basti1302',
6    repo: 'traverson',
7    sha: '5c82c74583ee67eae727466179dd66c91592dd4a'
8  }).getResource(function(err, resource) {
9    if (err) { console.log(err); return; }
10    console.log(resource)
11  })

Das ist deutlich kürzer als die erste Version und es wird nur ein Callback benötigt, der erst aufgerufen wird, wenn die Ziel-Ressource erreicht ist.

Was genau passiert in diesem Code-Beispiel? Traverson ruft die Wurzel-URI ab, die über die Methode from() vorgegeben wird. Von da aus sucht es sich selbstständig seinen Weg durch die API, in dem es den Links folgt, die der Methode follow übergeben wurden. Zum Schluss übergibt Traverson die letzte Ressource in dieser Kette dem Callback. Tatsächlich passiert das alles erst, wenn die Methode getResource aufgerufen wird, alle anderen Methoden sind nur vorbereitende Konfiguration.

Traverson Features

URI Templates

Abgesehen vom Folgen von Links bietet Traverson noch einige weitere Features. Eins davon haben wir im obigen Beispiel bereits benutzt, das Auflösen von URI-Templates.

Oft ist der Verweis zur nächsten Ressource keine konkrete URI sondern ein RFC 6570 URI-Template . Wenn Traverson ein solches Template erkennt und wenn Werte für die Template-Parameter über die Methode withTemplateParameters zur Verfügung gestellt wurden, werden die Platzhalter im Template automatisch ersetzt.

Abgesehen von URI-Templates bietet Traverson noch eine Reihe anderer nützlicher Features:

• basic authentication,
• OAuth,
• beliebige HTTP Header,
• JSONPath,
• HAL (hypertext application language)

Im Folgenden werden einige davon im Detail beschrieben.

JSONPath

Bis jetzt haben wir die Links, denen Traverson folgen soll, dadurch bestimmt, dass wir der Methode follow eine Reihe von Property-Namen übergeben haben. Traverson sucht in jeder Ressource jeweils nach dem Property-Namen, um herauszufinden, welche URI als nächstes abgerufen werden muss.
Hier stellt sich die Frage, was passiert, wenn der Link kein direktes Property der Ressource ist. Wenn zum Beispiel die Ressource so aussieht:

1{
2  "deeply": {
3    "nested": {
4      "link: "http://api.io/congrats/you/have/found/me"
5    }
6  }
7}

Um den Link zu http://api.io/congrats/you/have/found/me zu folgen, kann man der Methode follow auch JSONPath -Ausdrücke übergeben:

1api.newRequest()
2  .follow('$.deeply.nested.link')
3  .getResource(function(error, document) {
4    ...
5  })

Natürlich lassen sich JSONPath-Ausdrücke und normale Property-Namen in einem Aufruf von follow mischen.

Basic Authentication

Unter der Haube benutzt Traverson das zuvor erwähnte request-Modul, zumindest unter Node.js. (In Browser wird request durch einen auf superagent basierenden Shim ersetzt.) Daher können alle Features von request, wie Basic Authentication, OAuth und das Senden von beliebigen HTTP-Headern auch mit Traverson benutzt werden. Basic Authentication mit der GitHub API sähe so aus:

1var api = require('traverson').json.from('https://api.github.com/'),
2    ghUser = 'basti1302',
3    ghPass = '...'
4 
5api.newRequest()
6  .follow(...)
7  .withRequestOptions({
8    auth: {
9      user: ghUser,
10      pass: ghPass,
11      sendImmediately: true
12    }
13  }).getResource(function(err, resource) {
14    ...
15  })

HAL – Hypertext Application Language

HAL, die Hypertext Application Language, ist ein einfaches Format, das es ermöglicht, Ressourcen in einer API auf einfache und konsistente Weise untereinander zu verlinken. Es gibt eine formale Spezifikation für dieses Format und den Media Type application/hal+json. HAL lässt sich nicht darüber aus, wie die eigentlichen Inhalte in JSON dargestellt werden sollen. Es beschreibt ausschließlich, wie und wo die Hyperlinks präsentiert werden. Dies erleichtert die Implementierung von Clients, da immer klar ist, wo im Dokument die Links zu finden sind, auch, wenn ein Client mit verschiedenen APIs redet. Wenn man dort zum Beispiel von der Wurzel-Ressource über die Links ht:users, ht:user und ht:posts navigiert, erreicht man die Liste der Posts für einen Benutzer.

Das geht auch mit Traverson. Dazu benutzt man require('traverson').jsonHal statt require('traverson').json.

1var api = require('traverson').jsonHal.from('http://haltalk.herokuapp.com/')
2 
3api.newRequest()
4  .withRequestOptions({
5    headers: {
6      'Accept': 'application/json',
7      'Content-Type': 'application/json'
8    }
9  }).follow('ht:users', 'ht:user', 'ht:posts', 'ht:post')                                                                      
10  .withTemplateParameters({name: 'mike'})                                   
11  .getResource(function(error, document) {
12     // document will represent the list of posts for user mike
13  })

Möchte man hingegen einen neuen Eintrag posten, sähe das so aus:

1var body = { content: 'Hello there!' }
2api.newRequest()
3  .withRequestOptions({
4    headers: {
5      'Accept': 'application/json',
6      'Content-Type': 'application/json'
7    },
8    auth: {
9      user: 'traverson',
10      pass: '...', // traverson's password would go here :-)
11      sendImmediately: true
12    }
13  }).follow('ht:me', 'ht:posts')
14  .withTemplateParameters({ name: 'traverson' })
15  .post(body, function(error, respons) {
16    if (err) { console.log(err); return; }
17    if (response.statusCode === 201) {
18      console.log('unexpected http status: ' + response.statusCode)
19    }
20  })

In beide Beispielen mussten wir die Header Accept und Content-Type setzen, damit der Haltalk-Server unseren Request korrekt bearbeitet. Da Haltalk das Posten nur angemeldeten Benutzern erlaubt, mussten wir im zweiten Beispiel auch Benutzer und Passwort mitliefern.

Im Browser

In server-seitigem JavaScript ist das Ansprechen von REST-APIs ein häufig auftretender Anwendungsfall. Deshalb ist Traverson zuerst als Node.js-Modul konzipiert worden. Allerdings kann Traverson sich im Browser als genauso nützlich erweisen, wenn man über AJAX mit REST-APIs arbeitet. Daher funktioniert Traverson dank browserify mittlerweile auch im Browser. Der Browser-Build ist eine einzelne Datei mit einer UMD die entweder per script-Tag eingebunden werden kann oder über einen AMD-Loader wie RequireJS geladen werden kann.

Die Benutzung von Traverson im Browser unterscheidet sich nicht von der Benutzung in Node.js:

1<html>
2  <head>
3    <meta charset="utf-8">
4    <title>Traverson in the Browser</title>
5    <script src="http://code.jquery.com/jquery-2.0.2.min.js"></script>
6    <script src="traverson.min.js"></script>
7  </head>
8  <body>
9 
10    <div id="response"/>
11 
12    <script>
13      var api = traverson.json.from('https://api.github.com/')
14      api.newRequest()
15        .follow('repository_url', 'commits_url', 'comments_url')
16        .withTemplateParameters({
17          owner: 'basti1302',
18          repo: 'traverson',
19          sha: '5c82c74583ee67eae727466179dd66c91592dd4a'
20        }).getResource(function(err, resource) {
21        if (err) {
22          $('#response').html(JSON.stringify(err))
23          return
24        }
25        $('#response').html('Hooray! The commit comment is <br/>"' +
26            resource[0].body + '"')
27      })
28    </script>
29  </body>
30</html>