restl

Restl - A hypermedia client for nodejs

Important note: this package is currently pretty experimental and not complete. Use at your own risk.

Introduction

This NPM package is an attempt at creating a 'generic' hypermedia client, it supports an opiniated set of modern features REST services might have.

This means that there's a strong focus on links and link-relationships. Initially we'll build in strong support for Web Linking, a.k.a. the HTTP Link header, and HAL.

Installation

npm install --save restl

Goals

For 1.0:

• PUT request.
• DELETE request.
• Global resource cache.
• Expand CURIES automatically.
• Resolve every URI to an absolute URI.
• Figuring out _embedded.
• Support HTTP Link header.
• Support non-JSON resources, including things like images.
• Parse HTML5 links.
• Parse Atom.

Post 1.0

• Support for HAL Forms.
• Parse and respect HTTP Cache headers.
• Support Prefer: return=representation.

Already done:

• Following links.
• Basic HAL parsing.

Usage

Fetching a resource and following a link:

var restl = require('restl')('http://my-hal-api.example.org/');

// Fetch the home resource
var home = restl.getResource()
// Then get the 'author' relationship from _links
home.follow('author')
  .then(function(authorResource)) {

    // Follow the 'me' resource.
    return authorResource.follow('me');

  }.then(function(meResource) {

    // Get the full body
    return meResource.get();

  }.then(function(meBody) {

    // Output the body
    console.log(meBody);

  }).catch(function(err) {

    // Error
    console.log(err);

  });

Providing custom options

restl uses request under the hood to do HTTP requests. Custom options can be specified as such:

var bookMark = 'https://my-hal-api.example.org';
var options {
  auth: {
    user: 'foo',
    pass: 'bar'
  }
}

var restl = require('restl')(bookMark, options);

For a full list of possible options, check out the request documentation.

API

Client

Constructor

var client = new Client(bookMark, options);

• bookMark - The base URL of the web service.
• options optional - A list of options for Request.

Client.getResource()

Returns a 'Resource' object based on the url. If

var resource = client.getResource(url);

• url - URL to fetch. Might be relative. If not provided, the bookMark is fetched instead.

This function returns a Resource.

Resource

Resource.get()

Returns the result of a GET request. This function returns a Promise.

resource.get().then(function(body) {
  console.log(body);
});

If the resource was fetched earlier, it will return a cached copy.

Resource.refresh()

Refreshes the internal cache for a resource and does a GET request again. This function returns a Promise that resolves when the operation is complete, but the Promise does not have a value.

resource.refresh().then(function() {
  return resource.get()
}).then(function(body) {
  // A fresh body!
});

Resource.links()

Returns a list of Link objects for the resource.

resource.links().then(function(links) {
  console.log(links);
});

Resource.follow()

Follows a link, by it's relation-type and returns a new resource for the target.

resource.follow('author').then(function(author) {
  return author.get();
}).then(function(body) {
  console.log(body);
});