This is the YAWP! Framework javascript client.

It streamlines the access to your REST APIs from Node.js or a browser.

Contents

• Installation
• Setup
• Repository Actions
• Custom Actions
• Query
• Transformers
• Instance Methods
• Class Extension
• ES5 Prototypes

Installation

Web

<script src="https://rawgit.com/feroult/yawp/yawp-1.6.8/yawp-client/lib/web/yawp.min.js"></script>

NodeJs

npm install yawp --save

Note: if your environemnt doesn't support ES6 promises, you'll need to use a polyfill like this one.

Setup

By default the client routes all API calls to the path /api of the current app's host. You can override this setting as following:

yawp.config(function (c) {
    c.baseUrl('http://your-cors-host.com/api');
});

Repository Actions

// create
yawp('/people').create({ name: 'janes' }).done(function (person) {
    console.log(person);
});

// update
yawp('/people/1').update({ name: 'janes' }).done(function (person) {
    console.log(person);
});

// patch
yawp('/people/1').patch({ name: 'janes' }).done(function (person) {
    console.log(person);
});

// destroy
yawp('/people/1').destroy().done(function (id) {
    console.log(id);
});

// fetch
yawp('/people/1').fetch(function (person) {
    console.log(person);
});

// list
yawp('/people').list(function (people) {
    console.log(people);
});

Custom Actions

// @GET("me") over collection action
yawp('/people').get('me').done(function (person) {
    console.log(person);
});

// @PUT("reverse-name") single entity action
yawp('/people/1').put('reverse-name').done(function (person) {
    console.log(person);
});

Query

// where + list
yawp('/people').where(['name', '=', 'janes']).list(function (people) {
    console.log(people);
});

// where + first
yawp('/people').where(['name', '=', 'janes']).first(function (person) {
    console.log(person);
});

// limit
yawp('/people').where(['name', '=', 'janes']).limit(10).list(function (people) {
    console.log(people);
});

// order
yawp('/people').where(['name', '=', 'janes']).order([{ p: 'name', d: 'asc'}])
               .list(function (people) {
    console.log(people);
});

Transfomers

// transform + where + list
yawp('/people').transform('upperCase').where(['name', '=', 'janes']).list(function (people) {
    console.log(people);
});

// transform + first
yawp('/people').transform('upperCase').first(function (person) {
    console.log(person);
});

Instance Methods

All objects returned by the yawp query methods are wrapped inside an instance of the class Yawp. This class gives us some methods that operate over those instances:

yawp('/people/1').fetch(function (person) {
    person.name = 'new name';
    person.save(); // returns a promise
    person.put('active'); // returns a promise
    person._delete('active'); // returns a promise
    person.destroy(); // returns a promise
});

The complete API methods of the Yawp class can be found here.

Class Extension

All yawp client features can be extendend by subclassing the base Yawp class for a given endpoint. And this can be done either with the ES6 class syntax or with ES5 prototypes.

For instance, to create a Person class to add and encapsulate some new methods to the endpoint /people, we can do something this:

class Person extends yawp('/people') {
}

Now to add static methods to this endpoint model, we can do:

class Person extends yawp('/people') {
    static active() {
        return this.where('status', '=', 'ACTIVE');
    }
}

Note that now all the objects returned by the API calls using Person will be wrapped inside an instance of the Person class. With this, it is also possible to add methods that operate over instances of that class:

class Person extends yawp('/people') {
    static inactive() {
        return this.where('status', '=', 'INACTIVE');
    }

    activate() {
        return this.put('active');
    }
}

And use then in our application code:

Person.inative.first(function (person) {
    person.activate().then(function() {
        console.log('person is now active');
    });
})

Finally, we can override methods:

class Person extends yawp('/people') {
    save() {
        console.log('saving...');
        return super.save();
    }
}

ES5 Prototypes

If we are running our app in an environment that doesn't support ES6 class syntax, we have two options. The first is to transpile our ES6 code to ES5 using the Babel JS. The other is to use some convenience YAWP! methods. To create the same Person class as above but in ES5 we can do:

var Person = yawp('/people').subclass(/* we can pass a constructor function */);

Person.inactive = function() {
    return this.where('status', '=', 'INACTIVE');
}

Person.prototype.activate = function() {
    return this.put('active');
}

If we want to override methods, there is a small difference from the ES6 version. With ES5 we have to access the super methods using the syntax this.super, like this:

Person.prototype.save = function() {
    console.log('saving...');
    return this.super.save();
}