<table> <tr> <td><img width="20" src="https://cdnjs.cloudflare.com/ajax/libs/octicons/8.5.0/svg/archive.svg" alt="archived" /></td> <td><strong>Archived Repository</strong><br /> This code is no longer maintained. Feel free to fork it, but use it at your own risks. </td> </tr> </table>

restful.js

A pure JS client for interacting with server-side RESTful resources. Think Restangular without Angular.

Note: All examples written in this README use the ES6 specification.

Installation

It is available with bower or npm:

bower install restful.js
npm install restful.js

The dist folder contains two built versions which you can use to include either restful.js or a standalone version. Standalone version already embeds fetch.

Alternately, you can use a module loader like webpack.

import restful from 'restful.js';

Usage

Create a resource targeting your API

Restful.js needs an HTTP backend in order to perform queries. Two http backend are currently available:

fetch: For using restful.js in a browser.
request: For using restful.js in Node.js. There are defined as optional dependencies and therefore you must install them either with npm or bower depending your package manager.

Start by defining the base endpoint for an API, for instance http://api.example.com with the good http backend.

For a browser build :

import whatwg-fetch;
import restful, { fetchBackend } from 'restful.js';

const api = restful('http://api.example.com', fetchBackend(fetch));

For a node build :

import request from 'request';
import restful, { requestBackend } from 'restful.js';

const api = restful('http://api.example.com', requestBackend(request));

For those who prefers a ready-to-go version, pre built version of restful.js with fetch are available into the dist folder.

Collections and Members endpoints

A collection is an API endpoint for a list of entities, for instance http://api.example.com/articles. Create it using the all(name) syntax:

const articlesCollection = api.all('articles');  // http://api.example.com/articles

articlesCollection is just the description of the collection, the API wasn't fetched yet.

A member is an API endpoint for a single entity, for instance http://api.example.com/articles/1. Create it using the one(name, id) syntax:

const articleMember = api.one('articles', 1);  // http://api.example.com/articles/1

Just like above, articleMember is a description, not an entity.

You can chain one() and all() to target the required collection or member:

const articleMember = api.one('articles', 1);  // http://api.example.com/articles/1
const commentsCollection = articleMember.all('comments');  // http://api.example.com/articles/1/comments

Custom endpoint URL

In case you need to set a custom endpoint URL, you can use custom methods.

const articleCustom = api.custom('articles/beta');  // http://api.example.com/articles/beta

// you can add an absolute url
const articleCustom = api.custom('http://custom.url/articles/beta', false);  // http://custom.url/articles/beta

A custom endpoint acts like a member, and therefore you can use one and all to chain other endpoint with it.

Entities

Once you have collections and members endpoints, fetch them to get entities. Restful.js exposes get() and getAll() methods for fetching endpoints. Since these methods are asynchronous, they return a native Promise for response.

If your application does not support native Promise, you can use a polyfill.

const articleMember = api.one('articles', 1);  // http://api.example.com/articles/1
articleMember.get().then((response) => {
    const articleEntity = response.body();

    const article = articleEntity.data();
    console.log(article.title); // hello, world!
});

const commentsCollection = articleMember.all('comments');  // http://api.example.com/articles/1/comments
commentsCollection.getAll().then((response) => {
    const commentEntities = response.body();

    commentEntities.forEach((commentEntity) => {
        const comment = commentEntity.data();
        console.log(comment.body);
    })
});

Tip: You can describe a member based on a collection and trigger the API fetch at the same time by calling get(id):

// fetch http://api.example.com/articles/1/comments/4
const articleMember = api.one('articles', 1);
const commentMember = articleMember.one('comments', 4);
commentMember.get().then((response) => {
    //
});
// equivalent to
const commentsCollection = articleMember.all('comments');
commentsCollection.get(4).then((response) => {
    //
});

Response

A response is made from the HTTP response fetched from the endpoint. It exposes statusCode(), headers(), and body() methods. For a GET request, the body method will return one or an array of entities. Therefore you can disable this hydration by calling body(false).

Headers

For most of cases, headers in a response will be a plain object with headers data, but for some browsers, that don't support iteration over Headers object, it will simply be returned as a Headers object, so you can use get method from it to get required headers.

Entity Data

An entity is made from the HTTP response data fetched from the endpoint. It exposes a data() method:

const articleCollection = api.all('articles');  // http://api.example.com/articles

// http://api.example.com/articles/1
api.one('articles', 1).get().then((response) => {
    const articleEntity = response.body();

    // if the server response was { id: 1, title: 'test', body: 'hello' }
    const article = articleEntity.data();
    article.title; // returns `test`
    article.body; // returns `hello`
    // You can also edit it
    article.title = 'test2';
    // Finally you can easily update it or delete it
    articleEntity.save(); // will perform a PUT request
    articleEntity.delete(); // will perform a DELETE request
}, (response) => {
    // The reponse code is not >= 200 and < 400
    throw new Error('Invalid response');
});

You can also use the entity to continue exploring the API. Entities expose several other methods to chain calls:

entity.one ( name, id ): Query a member child of the entity.
entity.all ( name ): Query a collection child of the entity.
entity.url (): Get the entity url.
entity.save ( [, data [, params [, headers ]]] ): Save the entity modifications by performing a POST request.
entity.delete ( [, data [, params [, headers ]]] ): Remove the entity by performing a DELETE request.
entity.id (): Get the id of the entity.

const articleMember = api.one('articles', 1);  // http://api.example.com/articles/1
const commentMember = articleMember.one('comments', 3);  // http://api.example.com/articles/1/comments/3
commentMember.get()
    .then((response) => {
        const commentEntity = response.body();

        // You can also call `all` and `one` on an entity
        return comment.all('authors').getAll(); // http://api.example.com/articles/1/comments/3/authors
    }).then((response) => {
        const authorEntities = response.body();

        authorEntities.forEach((authorEntity) => {
            const author = authorEntity.data();
            console.log(author.name);
        });
    });

entity.id() will get the id from its data regarding of the identifier of its endpoint. If you are using another name than id you can modify it by calling identifier() on the endpoint.

const articleCollection = api.all('articles');  // http://api.example.com/articles
articleCollection.identifier('_id'); // We use _id as id field

const articleMember = api.one('articles', 1);  // http://api.example.com/articles/1
articleMember.identifier('_id'); // We use _id as id field

Restful.js uses an inheritance pattern when collections or members are chained. That means that when you configure a collection or a member, it will configure all the collection on members chained afterwards.

// configure the api
api.header('AuthToken', 'test');
api.identifier('_id');

const articlesCollection = api.all('articles');
articlesCollection.get(1); // will send the `AuthToken` header
// You can configure articlesCollection, too
articlesCollection.header('foo', 'bar');
articlesCollection.one('comments', 1).get(); // will send both the AuthToken and foo headers

API Reference

Restful.js exposes similar methods on collections, members and entities. The name are consistent, and the arguments depend on the context.

Collection methods

addErrorInterceptor ( interceptor ): Add an error interceptor. You can alter the whole error.
addRequestInterceptor ( interceptor ): Add a request interceptor. You can alter the whole request.
addResponseInterceptor ( interceptor ): Add a response interceptor. You can alter the whole response.
custom ( name [, isRelative = true ] ): Target a child member with a custom url.
delete ( id [, data [, params [, headers ]]] ): Delete a member in a collection. Returns a promise with the response.
getAll ( [ params [, headers ]] ): Get a full collection. Returns a promise with an array of entities.
get ( id [, params [, headers ]] ): Get a member in a collection. Returns a promise with an entity.
head ( id [, params [, headers ]] ): Perform a HEAD request on a member in a collection. Returns a promise with the response.
header ( name, value ): Add a header.
`h

Restful.js

Install / Use

README