traverson-angular

AngularJS integration for Traverson, the JS Hypermedia Client

Introduction

traverson-angular offers seamless integration of Traverson with AngularJS. Traverson comes in handy when consuming REST APIs that follow the HATEOAS principle, that is, REST APIs that have links between their resources. If you don't know Traverson, you should probably have a look at its GitHub page or at this introductory blog post first.

traverson-angular wraps Traverson in an AngularJS module and converts the original callback based API into an API based on promises.

Installation

npm

See below.

Download

You can grab a download from the latest release. All downloads include traverson-angular and a bundled Traverson library, so you do not need to include Traverson separately. Here are your options:

• traverson-angular.min.js: Minified build with UMD. This build can be used with a script tag or with an AMD loader like RequireJS (untested). It will register the AngularJS module traverson, which you can use as a dependency of your module (see below). If in doubt, use this build.
• traverson-angular.js: Non-minified build with UMD. Same as above, just larger.
• traverson.external.min.js: Minified require/external build. Created with browserify's --require parameter and intended to be used (required) from other browserified modules, which were created with --external traverson-angular. This build could be used if you use browserify but do not want to bundle traverson-angular and Traverson with your own browserify build but keep it as a separate file.
• traverson.external.js: Non-minified require/external build, same as before, just larger.

Bower

bower install traverson-angular --save

Usage

angular.module('my-app', ['traverson']);

angular.module('my-app').service('apiService', function(traverson) {
  ...
});

Have a look at the examples in the repository:

• Example 1 (JavaScript here)
• GitHub API example (JavaScript here)

Using npm and Browserify

If you are using npm and Browserify and writing your AngularJS app as CommonJS modules, instead of downloading a release, you can install it with npm install traverson-angular -S.

This is how your code using traverson-angular would look like:

var angular = require('angular');
var traverson = require('traverson-angular');
var app = angular.module('my-app', [traverson.name]);
 
...
 
app.service('apiService', function(traverson) {
  ...
});
 

See here for a complete, working example of a CommonJS based AngularJS app using traverson-angular, build with Browserify.

To require angular-core like this, you need a shim in your package.json, like this:

{
  ...
  "dependencies": {
    "angular": "^1.3.4",
    ...
  },
  "browser": {
    "angular": "./angular/angular-common-js.js"
  }
}
 

angular-common-js.js:

require('./angular.js');
module.exports = angular;

Browserify your app as usual - Browserify will include traverson-angular, Traverson itself and its dependencies for you.

API

You should refer to Traverson's docs for general info how to work with Traverson. Anything that works with Taverson also works with traverson-angular. The only difference is that traverson-angular's methods are not callback-based but work with promises.

So this code, which uses Traverson directly:

traverson
.from('http://api.example.com')
.newRequest()
.follow('link_to', 'resource')
.getResource(function(error, document) {
  if (error) {
    console.error('No luck :-)')
  } else {
    console.log('We have followed the path and reached our destination.')
    console.log(JSON.stringify(document))
  }
});

becomes this with traverson-angular:

traverson
.from('http://api.example.com')
.newRequest()
.follow('link_to', 'resource')
.getResource()
.result
.then(function(document) {
  console.log('We have followed the path and reached our destination.')
  console.log(JSON.stringify(document))
}, function(err) {
  console.error('No luck');
});

The only difference is .getResource(function(error, document) { => .getResource().result.then(function(document) {.

Actually, the object returned by getResource has three properties:

• result: the promise representing the link traversal,
• continue: a function that can be used to continue a finished link traversal and
• abort: a function that can be used to abort link traversal that is in progress.

The following action methods of the Traverson request builder return such an object ({ result, continue, abort }) when used via traverson-angular:

• get()
• getResource()
• getUri()
• post(payload)
• put(payload)
• patch(payload)
• delete

How HTTP Status Code Are Handled

In contrast to AngularJS' $http service, Traverson and traverson-angular do not interpret status codes outside of the 2xx range as an error condition. Only network problems (host not reachable, timeouts, etc.) lead to a rejection of the promise, that is, only those trigger the error callback. Completed HTTP requests, even those with status 4xx or 5xx are interpreted as a success and trigger the success callback. This applies only to the last request in a traversal, HTTP requests during the traversal that respond with 4xx/5xx are interpreted as an error (because the traversal can not continue).

This also holds when using .useAngularHttp() (see below).

Using AngularJS' $http Service Instead Of Traverson's HTTP Module

Traverson has it's own HTTP module (based on superagent) and by default, this is used to make HTTP requests. If you want to use Traverson in a project that makes use of AngularJS' $http service and its configuration possibilities (default headers, interceptors and so on), these configurations do not apply automatically to the requests issued by Traverson. If you want that, you can configure traverson-angular to use $http instead of Traverson's HTTP module by calling useAngularHttp() on the request builder.

Example:

traverson
.from('http://api.example.com')
.useAngularHttp()
.newRequest()
.follow('link_to', 'resource')
.getResource()
.result
.then(function(document) {
  ...
});

Continuing a Link Traversal

See Traverson's README for a general description of the continue() feature. This section just describes how to use it with traverson-angular.

The object returned by the action methods (get, getResource, getUrl, post, put, patch, delete) have a property continue which is a function that can be used to obtain a promise that is resolved when the link traversal finishes (as does the result promise) and which gives you a request builder instance that starts at the last URL/resource of the finished link traversal. It can be used just as the standard request builder. That is, it has the same configuration and action methods. It enables you to continue the link traversal from the last target resource and follow more links from there.

So while with plain vanilla Traverson (not traverson-angular) you would continue a successful link traversal process like this:

traverson
.from(rootUrl)
.follow('link1', 'link2')
.getResource(function(err, firstResource, traversal) {
  if (err) { return done(err); }
  // do something with the first resource, maybe decide where to go from here.
  traversal
  .continue()
  .follow('link3', 'link3')
  .getResource(function(err, secondResource) {
    if (err) { return done(err); }
    // do something with the second resource
  });
});

...this is how it is done with traverson-angular:

var request =
traverson
.from('http://api.example.com')
.follow('link1', 'link2');
.getResource();

request.result.then(successCallback, errorCallback);

request.continue().then(function(request) {
  request
  .follow('link3', 'link4');
  .getResource()
  .result
  .then(successCallback2, errorCallback2);
});

Aborting the Link Traversal

As mentioned above, the object returned by the action methods returns an object which also has an abort() function.

So while with plain vanilla Traverson (not traverson-angular) you would abort a link traversal process like this

var handle =
traverson
.from('http://api.example.com')
.newRequest()
.follow('link_to', 'resource')
.getResource(...);

// abort the link traversal
handle.abort();

...this is how it is done with traverson-angular:

var handle =
traverson
.from('http://api.example.com')
.newRequest()
.follow('link_to', 'resource')
.getResource();

// register callbacks
handle.result.then(successCallback, errorCallback);

// abort the link traversal
handle.abort()

traverson-angular With Media Type Plug-Ins

You can use all media type plug-ins that are available for Traverson with traverson-angular. Here is how:

• Make sure the JavaScript for the media type plug-in has been loaded (for example, add a script tag for traverson-hal.min.js).
• Register the media type with a line like this: traverson.registerMediaType(TraversonJsonHalAdapter.mediaType, TraversonJsonHalAdapter);.
• If necessary force Traverson to use the media type in question with setMediaType(...) (for HAL, you can use the convenience method .jsonHal() instead).
• If necessary, add Accept headers so your server knows you want to receive a particular media type. Example: .withRequestOptions({ headers: { 'accept': 'application/hal+json' } }).

Here is a snippet outlining how to use traverson-angular with traverson-hal:

<script src="traverson-angular.min.js"></script>
<script src="traverson-hal.min.js"></script>

traverson.registerMediaType(TraversonJsonHalAdapter.mediaType,
                            TraversonJsonHalAdapter);
traverson
.from(rootUri)
.jsonHal()
.withRequestOptions({ headers: { 'accept': 'application/hal+json' } })
.follow(...)
.getResource()
.result
.then(...);

You can find a complete working example for integrating traverson-hal with traverson-anglar in browser/example/hal.html and browser/example/hal.js.

Contributing

See Contributing to traverson-angular.

Code of Conduct

See Code of Conduct.

Release Notes

See CHANGELOG.

License

MIT