hateoas-client.js README

• Latest Release:
• Build-Status:
• Official Site: http://dracoblue.net/

hateoas-client.js is copyright 2011-2015 by DracoBlue http://dracoblue.net

What is hateoas-client.js?

hateoas-client.js is a library (for browser+nodejs) to communicate with RESTful services. It uses jQuery as ajax library. It's aim is to provide a very simple API to follow the links defined in a request response, thus achieving level 3 in Richardson Maturity Model.

Requirements:

• jQuery 1.5+

Installation

• On the browser: $ bower install hateoas-client
• In nodejs: $ npm install hateoas-client

How does it work?

Example with JSON (in the browser)

If you include hateoas-client.js after your jQuery.js, you'll have the ability to make such requests:

var a = new HttpAgent('/api');
a.navigate(['coffee', {'name': 'Small'}, "buy"]);
a.post(function(response) {
    // response.getValue() contains what the POST /api/orders?product_id=5 returned
});

This example assumes that the responses contain

GET /api
    {
        "links": [ { "rel": "coffee", "href": "/api/coffee" } ]
    }
GET /api/coffee
    [
        {
            "id": 5,
            "name": "Small",
            "links": [ { "rel": "buy", "href": "/api/orders?product_id=5" } ]
        }
    ]

Remote Example with Atom-Feed

This example retrieves the most viewed videos from youtube, navigates 2x next, chooses the first element (because of empty filter{}), navigates to it's self link and finally: returns the <title> element's text.

var a = new HttpAgent('http://gdata.youtube.com/feeds/api/standardfeeds/most_viewed?max-results=5', {}, {
    'proxy_script': 'proxy.php?url='
});

a.navigate(['next', 'next', {}, 'self']);
a.get(function(response) {
    var title = jQuery(response.getValue()).find('title').text();
});            

That example also shows, how one can use the proxy_script-option to use a .php-script to retrieve contents from a remote site.

Usage with require.js

If you want to retrieve the HttpAgent in your require.js script use (ensure that hateoas-client-js maps on hateoas-client.js in your requirejs config file):

require('hateoas-client', function(hateoasClient) {
    var a = new hateoasClient.HttpAgent('/api');
});

Todos

• test and extend support for other responses (xml, maybe a generic converter system or usage of the one from jQuery)
• handle status codes other then 200 (currently only 200 is JsonHttpResponse#isOk() == true and 201 is interpreted)
• add documentation for HttpAgent, JsonHttpResponse, AtomXmlHttpResponse and XmlHttpResponse
• support mimetypes
• ... more as soon as I get to that!

Changelog

• 0.3.0 (2015/04/06)
  • in case of unsupported media type return UnsupportedMediaTypeHttpResponse
  • added server test
  • inject agent also in subresponses of json, hal and atom response
  • handle Location-redirects with / at the beginning on 201 Status Code
  • added HttpAgent#logDebug and HttpAgent#logTrace (enable it with HttpAgent.enableLogging=true; )
• 0.2.0 (2015/04/04)
  • added mocha test infrastructure
  • renamed to hateoas-client.js
  • handle relative paths in links (by asking HttpAgent for the base url)
  • Added FIXME method for getLinks on HTML/XML objects
  • added nodejs support with domino, jquery and xmlhttprequest for nodejs
  • added HttpAgent#getBaseUrl
• 0.1.0
  • added definition for requirejs
  • added JsonHalHttpResponse for HAL hyper media type
  • fixes JsonHttpResponse xhr variable on sub values
  • added AtomXmlHttpResponse and example for atom feed retrieval
  • added filtering * + object to breadth first search for anything until it matches a filter object
  • added handler for 201 Created response
  • added handling for status code 200
  • added * as indicator for breadth first search in HttpAgent#navigate
  • added function as filter object
  • example files added
  • initial commit

License

hateoas-client.js is licensed under the terms of MIT. See LICENSE for more information.