Alloy REST API Adapter with built in caching support

A rest api adapter for appcelerator alloy that has built in caching

the caching code was refactored from this repo https://gist.github.com/johnthethird/560183

The REST adapter is one of the most used adpaters on projects that we build here a Clearly Innovative. Also integrating third party APIs with request limits and just for overall performance benefits we felt the need to cache data at various times.

Also we believe that the rest api for alloy should stay true to the original backbonejs model so we have not made any modifications to the why the adapter functions. It has been written so your code that interacts with alloy models can be used in a javascript application with the default backbone sync adapter.

Enjoy, if you have issues, please log them

How it works

Using the Cache

The settings can be added as configuration options when setting up you model. the adapter will use these values by default unless value is specified on the model or in the options on the sync adapter call

/**
 * Model used to perform a global search on the API
 */

exports.definition = {
    config : {
        adapter : {
            type : "restapi_c",
        },
        cacheSettings : {
            cacheSeconds : 3000,     // timeToLive default value
            pruneSeconds : 2520000,  // pruneSeconds default value anything this old is GONE!!
        }
    },
    //
    // THE MODEL
    extendModel : function(Model) {
        _.extend(Model.prototype, {
        });
        return Model;
    },
    //
    // THE COLLECTION
    extendCollection : function(Collection) {

        _.extend(Collection.prototype, {
        });
        return Collection;
    }
};

you would setup the call like this when using it with your model

var UserPhotos = Alloy.Collections.instance('UserPhotos');
UserPhotos.fetch({
    timeToLive : 3000,    // how long in ms for item to persist in cache
    ignoreCache : false,  // can ignore cache completely and make the api call always
    success : function(_collection, _response) {
        Ti.API.info('OUTPUT');
        Ti.API.info(JSON.stringify(_collection.models, null, 2));
    },
    error : function(_error, _response) {

    }
});

If your response was cached content, the returned object will contain metadata about the cached data. The adapter will add a new cacheInfo object the JSON results that will look like this

cacheInfo : {
    cached : true,
    cached_at : "2014-02-19 00:08:05"
}

If you are interested in passing the cache information all the way through to your Alloy model, in most cases you would need to utilize the BackboneJS method on your object call parse; see documentation here for additional information.

but your code in the Alloy model would look like this

parse: function(_response) {
    var model = this;
    
    var models = [];
    
    // loop through all data in collection, create model and add to set
    models = _.map(_response.data, function(_i) {
        return new model(_i);
    });
    
    // save all of the pagination information for the model
    model.pagination = _response.pagination;
    
    // save any caching information for the model
    model.cacheInfo = _response.cacheInfo;
    
    // return the object to be returned collection
    return models;
},

When processing a JSON response from the API that look like this; the _response parameter would contain the data.

{
    "pagination": {
        "next_url": "https://api.instagram.com/v1/users/247944034/media/recent?max_id=fffff&client_id=XXX",
        "next_max_id": "645906744555277618_247944034"
    },
    "meta": {
        "code": 200
    },
    "data": [
        // INSTAGRAM JSON RESPONSE DATA - These will all be models added to the collection
    ],
    "cacheInfo" : {
        cached : true,
        cached_at : "2014-02-19 00:08:05"        
    }
}

Using the Activity Window

you will need to provide a library for displaying loading activity; the library should support the following methods.

/* how long to wait before closing window */
activityWindow.setMaxTimeout();

/* show the window, with a message */ 
activityWindow.show([message to display]);

/* hide the window */
activityWindow.hide();

you would setup the call like this when using it with your model

var UserPhotos = Alloy.Collections.instance('UserPhotos');
UserPhotos.fetch({
    activityWindow : require('activityWindowLib'),
    activityWindowTimeout : 60000,
    success : function(_collection, _response) {
        Ti.API.info('OUTPUT');
        Ti.API.info(JSON.stringify(_collection.models, null, 2));
    },
    error : function(_error, _response) {

    }
});

you could also leverage the flexibility of javascript and do this

var UserPhotos = Alloy.Collections.instance('UserPhotos');

/* set the properties on the collection object */
UserPhotos.activityWindow = require('activityWindowLib');
UserPhotos.activityWindowTimeout = 60000;

/* fetch the objects for the collection */
UserPhotos.fetch({
    success : function(_collection, _response) {
        Ti.API.info('OUTPUT');
        Ti.API.info(JSON.stringify(_collection.models, null, 2));
    },
    error : function(_error, _response) {

    }
});

Events and Purging The Cache

The module responds to an application level event to purge the entire cache; app.purge.cache and it takes and optional parameter to display an alert with cache information when the purging is completed

Ti.App.fireEvent('app.purge.cache', {showAlert: false})

Or you can call the purge cache method on the the model, any model that is created withe the adapter can purge the entire cache. A nice optimization would be to only purge a specific object type, but I just thought of that !!

UserPhotos.save({
    type:'purge',
    onComplete: function(_response){
        Ti.API.debug( _response.itemsPurged + " Items were purged from cache");
    }
});

when the purge is completed, an event is fired to indicate the process has completed app.purged.cache the event returns information on the number of items purged from the cache

Ti.App.addEventListener('app.purged.cache', function(_event){
    Ti.API.debug( _event.itemsPurged + " Items were purged from cache");
}

License

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.