angularjs-rails-resource 1.0.0.pre.2 → 1.0.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e088a0ef4c31ca6952015c7e5bf25e29a3aeffa6
-  data.tar.gz: ceafd0fc62d19853922b36a79b3926cd1ca579c9
+  metadata.gz: f7ce09b68d048977e8091b90cd120e0f7836f183
+  data.tar.gz: 2c0eb42c1684eb64a5fd58e80a7adc8fed7e4e2f
 SHA512:
-  metadata.gz: 8715afd2c22e4a5341512ba1845d83c6b5044cb6592dec4574fe530f908866ad9a48cc9f51b1fcfefe977bd30cf8661e5e39f2240c61ed9a0237be1cb81a6e28
-  data.tar.gz: 93efebbbb2920fe2f2d6deb883bdfbe18cb8e5a720e93c946471deb1b9e8d6794820421e1dd4589179fc9643fb2c0eed90261458dbea030f05b291deda8f894c
+  metadata.gz: 6eb139ae046e2756eba924f354fbc386d752994ce43bbb67f5696f5c8567cc5ac49a125c7b687079c4766bce508dbd67dbc9c86097647e502daaf00952b01677
+  data.tar.gz: 56415e2fc32de4a5bd82db9cf0ece3ab680aa583bbb61a5df39bd2f8d14c95a2e74b3028c877da15f6fe648a86f6977937d1be9188d3971a4437d0ba295d3bf3

data/.gitignore

@@ -18,4 +18,5 @@ tmp
 test_out
 atlassian-ide-plugin.xml
 node_modules
+build/
 

data/CHANGELOG.md

@@ -3,7 +3,9 @@
 ## Bug Fixes
 
 ## Features
-- Added <code>configure</code> to allow changing configuration options after the resource has been initially configured.
+- Added <code>configure</code> function to allow changing configuration options after the resource has been initially configured.
+- Separated out RailsResource into separate service to allow subclassing without using the factories.
+- Added snapshot and rollback extension, be sure to check the [README](README.md#serializers) for details.
 
 ## Breaking Changes
 - <code>railsResourceFactoryProvider</code> settings have been moved to <code>RailsResourceProvider</code>
@@ -13,6 +15,60 @@
     - <code>enableRootWrapping</code> was renamed <code>rootWrapping</code>
     - <code>rootName</code> was renamed <code>name</code>
     - <code>rootPluralName</code> was renamed <code>pluralName</code>
+- Query parameters were not underscored previously.  We are now underscoring parameters by default.
+The configuration option <code>underscoreParams</code> can be set to false to disable the renaming.
+
+<a name="1.0.0-pre.3"></a>
+# 1.0.0-pre.3
+## Features
+- Added mixin capability, see [README](README.md#mixins) for details
+- Added snapshot and rollback extension, see [README](README.md#serializers) for details.
+- Added <code>underscoreParams</code> configuration option to allow turning off parameter underscore renaming.
+
+## Breaking Changes
+- Query parameters were not underscored previously.  We are now underscoring parameters by default.
+    The configuration option <code>underscoreParams</code> can be set to false to disable the renaming.
+
+<a name="1.0.0-pre.2"></a>
+# 1.0.0-pre.2
+## Bug Fixes
+- Support submitting array data (#85)
+
+<a name="1.0.0-pre.1"></a>
+# 1.0.0-pre.1
+## Bug Fixes
+
+## Features
+- Added <code>configure</code> function to allow changing configuration options after the resource has been initially configured.
+- Separated out RailsResource into separate service to allow subclassing without using the factories.
+
+## Breaking Changes
+- <code>railsResourceFactoryProvider</code> settings have been moved to <code>RailsResourceProvider</code>
+- <code>wrapData</code> config option has been renamed <code>rootWrapping</code>
+- All resource settings are now stored under the <code>config</code> property on the resource and should be modified using the <code>configure</code> function.
+- The following resource settings have been renamed:
+    - <code>enableRootWrapping</code> was renamed <code>rootWrapping</code>
+    - <code>rootName</code> was renamed <code>name</code>
+    - <code>rootPluralName</code> was renamed <code>pluralName</code>
+- Query parameters were not underscored previously.  We are now underscoring parameters by default.
+    The configuration option <code>underscoreParams</code> can be set to false to disable the renaming.
+- Replaced <code>railsRootWrappingTransformer</code> and <code>railsRootWrappingInterceptor</code> with <code>railsRootWrapper</code>
+    that has wrap & unwrap methods.  This eliminates the need for using promises during resource construction to handle unwrapping
+    data passed into the constructor.
+- Resource constructor no longer executes response interceptors.  If you need to customize the constructor you should look
+    at using subclassing instead.
+- <code>processResponse</code>, <code>transformData</code>, <code>callInterceptors</code> have all been removed as part of rewriting
+    the request / response handling.
+
+<a name="0.2.5"></a>
+# 0.2.5
+## Bug Fixes
+- Support submitting array data (#85)
+
+<a name="0.2.4"></a>
+# 0.2.4
+## Bug Fixes
+- Fix mapped name behavior when using serializer default exclusion (#81)
 
 <a name="0.2.3"></a>
 # 0.2.3

data/Gruntfile.js

@@ -1,14 +1,17 @@
 module.exports = function(grunt) {
-
   var path = require('path');
 
   var srcFolder = 'vendor/assets/javascripts/angularjs/rails/resource/',
       srcFiles = ["index.js", "utils/**/*.js", "serialization.js", "resource.js"].map(function(glob) {
         return srcFolder + glob;
+      }),
+      extensionFiles = ["extensions/**/*.js"].map(function(glob) {
+          return srcFolder + glob;
       });
 
   grunt.initConfig({
     pkg: grunt.file.readJSON('package.json'),
+
     meta: {
       banner: '/**\n' +
       ' * <%= pkg.description %>\n' +
@@ -17,9 +20,21 @@ module.exports = function(grunt) {
       ' * @author <%= pkg.author %>\n' +
       ' */\n'
     },
+
     dirs: {
-      dest: './'
+      dest: 'build'
+    },
+
+    clean: ['<%= dirs.dest %>'],
+
+    copy: {
+      extensions: {
+        files: [
+          {expand: true, flatten: true, src: extensionFiles, dest: '<%= dirs.dest %>/extensions'}
+        ]
+      }
     },
+
     concat: {
       options: {
         banner: "<%= meta.banner %>"
@@ -30,25 +45,35 @@ module.exports = function(grunt) {
         options: {
           process: function(src, filepath) {
             return src.replace(/^\/\/= require.*\n/gm, '');
-          },
-        },
+          }
+        }
       }
     },
-    zip: {
-      '<%= dirs.dest %>/angularjs-rails-resource.zip': ['<%= dirs.dest %>/<%= pkg.name %>.js', '<%= dirs.dest %>/<%= pkg.name %>.min.js']
+
+    compress: {
+      dist: {
+        options: {
+          archive: '<%= dirs.dest %>/angularjs-rails-resource.zip'
+        },
+        files: [
+          {expand: true, cwd: '<%= dirs.dest %>', src: ['**/*.js']}
+        ]
+      }
     },
+
     uglify: {
       options: {
         banner: "<%= meta.banner %>"
       },
       dist: {
-        files: {
-          '<%= dirs.dest %>/<%= pkg.name %>.min.js': ['<%= concat.dist.dest %>']
-        }
+        files: [
+          {expand: true, cwd: '<%= dirs.dest %>', src: ['**/*.js'], dest: '<%= dirs.dest %>', ext: '.min.js'}
+        ]
       }
     },
+
     jshint: {
-      files: ['gruntfile.js'],
+      files: ['gruntfile.js'].concat(srcFiles),
       options: {
         // options here to override JSHint defaults
         globals: {
@@ -56,9 +81,19 @@ module.exports = function(grunt) {
         }
       }
     },
+
     watch: {
       files: ['<%= jshint.files %>'],
-      tasks: ['jshint', 'qunit']
+      tasks: ['jshint']
+    },
+
+    bump: {
+      options: {
+        files: ['package.json', 'bower.json'],
+        commit: false,
+        createTag: false,
+        push: false
+      }
     }
   });
 
@@ -66,30 +101,10 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-contrib-jshint');
   grunt.loadNpmTasks('grunt-contrib-watch');
   grunt.loadNpmTasks('grunt-contrib-concat');
-  grunt.loadNpmTasks('grunt-zip');
-
-  grunt.registerTask('default', ['jshint', 'concat', 'uglify', 'zip']);
-
-  // Provides the "bump" task.
-  grunt.registerTask('bump', 'Increment version number', function() {
-    var versionType = grunt.option('type');
-    function bumpVersion(version, versionType) {
-      var type = {patch: 2, minor: 1, major: 0},
-          parts = version.split('.'),
-          idx = type[versionType || 'patch'];
-      parts[idx] = parseInt(parts[idx], 10) + 1;
-      while(++idx < parts.length) { parts[idx] = 0; }
-      return parts.join('.');
-    }
-    var version;
-    function updateFile(file) {
-      var json = grunt.file.readJSON(file);
-      version = json.version = bumpVersion(json.version, versionType || 'patch');
-      grunt.file.write(file, JSON.stringify(json, null, '  '));
-    }
-    updateFile('package.json');
-    updateFile('bower.json');
-    grunt.log.ok('Version bumped to ' + version);
-  });
+  grunt.loadNpmTasks('grunt-contrib-copy');
+  grunt.loadNpmTasks('grunt-contrib-clean');
+  grunt.loadNpmTasks('grunt-contrib-compress');
+  grunt.loadNpmTasks('grunt-bump');
 
+  grunt.registerTask('default', ['jshint', 'clean', 'concat', 'copy', 'uglify', 'compress']);
 };

data/README.md

@@ -26,18 +26,13 @@ Book.query({title: 'Moby Dick'}).then(function (books) {
 You can inject the <code>railsSerializerProvider</code> into your application config function and override the <code>underscore</code>
 and <code>camelize</code> functions:
 ````javascript
-angular.module('app').config(function (railsSerializerFactory) {
-    railsSerializerProvider.
-        underscore(function (name) {
-            return name;
-        }).
-        camelize(function (name) {
-            return name;
-        });
-});
+angular.module('app').config(["railsSerializerProvider", function(railsSerializerProvider) {
+    railsSerializerProvider.underscore(angular.identity).camelize(angular.identity);
+}]);
 ````
 
 ## Installation
+### Rails Asset Pipeline
 Add this line to your application's Gemfile to use the latest stable version:
 ```ruby
 gem 'angularjs-rails-resource', '~> 0.2.3'
@@ -47,6 +42,19 @@ Include the javascript somewhere in your asset pipeline:
 ```javascript
 //= require angularjs/rails/resource
 ```
+
+To add extensions just add additional requires:
+```javascript
+//= require angularjs/rails/resource/extensions/snapshots
+```
+
+### Standalone
+If you aren't using the Rails asset pipeline you can download the combined
+[angularjs-rails-resource.js](https://github.com/FineLinePrototyping/dist-angularjs-rails-resource/blob/master/angularjs-rails-resource.js)
+or [angularjs-rails-resource.min.js](https://github.com/FineLinePrototyping/dist-angularjs-rails-resource/blob/master/angularjs-rails-resource.min.js).
+
+You can also use [Bower](http://bower.io/) to install <code>angularjs-rails-resource</code>.
+
 ## Branching and Versioning
 As much as possible we will try to adhere to the [SemVer](http://semver.org/) guidelines on release numbering.
 
@@ -57,35 +65,71 @@ Release branches should remain stable but it is always best to rely on the ruby
 ## Changes
 Make sure to check the [CHANGELOG](CHANGELOG.md) for any breaking changes between releases.
 
-## Dependencies
-Since this is an [AngularJS](http://angularjs.org) module it of course depends on that but more specifically the it depends on the following AngularJS services:
-
-* [$http](http://docs.angularjs.org/api/ng.$http)
-* [$q](http://docs.angularjs.org/api/ng.$q)
-* [$injector](http://docs.angularjs.org/api/AUTO.$injector)
-* [$interpolate](http://docs.angularjs.org/api/ng.$interpolate)
-
 ## Usage
-There are a lot of different ways that you can use the resources and we try not to force you into any specific pattern
+There are a lot of different ways that you can use the resources and we try not to force you into any specific pattern.
+All of the functionality is packed in an AngularJS module named "rails" so make sure that your modules depend on that module
+for the dependency injection to work properly.
 
 There are more examples available in [EXAMPLES.md](EXAMPLES.md).
 
+### Defining Resources
+There are multiple ways that you can set up define new resources in your application.
+
+#### railsResourceFactory
+Similar to $resource, we provide a <code>railsResourceFactory(config)</code> function that takes a config object with the configuration
+settings for the new resource.  The factory function returns a new class that is extended from RailsResource.
 
-### Basic Example
-In order to create a Book resource, we would first define the factory within a module.
 ```javascript
 angular.module('book.services', ['rails']);
 angular.module('book.services').factory('Book', ['railsResourceFactory', function (railsResourceFactory) {
-    return railsResourceFactory({url: '/books', name: 'book'});
+    return railsResourceFactory({
+        url: '/books',
+        name: 'book'
+    });
 }]);
 ```
-We would then inject that service into a controller:
+
+#### RailsResource extension
+We also expose the RailsResource as base class that you can extend to create your own resource classes.  Extending the RailsResource class
+directly gives you a bit more flexibility to add custom constructor code.  There are probably ten different ways to extend the class but
+the two that we intend to be used are through CoffeeScript or through the same logic that the factory function uses.
+
+##### CoffeeScript
+To allow better integration with CoffeeScript, we expose the RailsResource as a base class that can be extended to create
+resource classes.  When extending RailsResource you should use the <code>@configure</code> function to set configuration
+properties for the resource.  You can call <code>@configure</code> multiple times to set additional properties as well.
+
+````coffeescript
+class Book extends RailsResource
+  @configure url: '/books', name: 'book'
+
+class Encyclopedia extends Book
+  @configure url: '/encyclopedias', name: 'encyclopedia'
+````
+
+##### JavaScript
+Since the purpose of exposing the RailsResource was to allow for CoffeeScript users to create classes from it the JavaScript way
+is basically just the same as the generated CoffeeScript code.  The <code>RailsResource.extendTo</code> function is a modification
+of the <code>__extends</code> function that CoffeeScript generates.
+
+````javascript
+function Resource() {
+    Resource.__super__.constructor.apply(this, arguments);
+}
+
+RailsResource.extendTo(Resource);
+Resource.configure(config);
+````
+
+### Using Resources
 ```javascript
 angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book', function ($scope, Book) {
     $scope.searching = true;
     // Find all books matching the title
-    $scope.books = Book.query({title: title});
-    $scope.books.then(function(results) {
+    $scope.books = Book.query({
+        title: title
+    });
+    $scope.books.then(function (results) {
         $scope.searching = false;
     }, function (error) {
         $scope.searching = false;
@@ -98,12 +142,17 @@ angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book'
     });
 
     // Create a book and save it
-    new Book({title: 'Gardens of the Moon', author: 'Steven Erikson', isbn: '0-553-81957-7'}).create();
+    new Book({
+        title: 'Gardens of the Moon',
+        author: 'Steven Erikson',
+        isbn: '0-553-81957-7'
+    }).create();
 }]);
 ```
 
-### Serializer
-When defining a resource, you can pass a custom [serializer](#serializers) using the <code>serializer</code> configuration option.
+### Custom Serialization
+When defining a resource, you can pass a custom [serializer](#serializers) using the <code>serializer</code> configuration option to
+alter the behavior of the object serialization.
 ```javascript
 Author = railsResourceFactory({
     url: '/authors',
@@ -117,7 +166,7 @@ Author = railsResourceFactory({
 ```
 You can also specify a serializer as a factory and inject it as a dependency.
 ```javascript
-angular.module('rails').factory('BookSerializer', function(railsSerializer) {
+angular.module('rails').factory('BookSerializer', function (railsSerializer) {
     return railsSerializer(function () {
         this.exclude('publicationDate', 'relatedBooks');
         this.rename('ISBN', 'isbn');
@@ -134,47 +183,14 @@ Book = railsResourceFactory({
     name: 'book',
     serializer: 'BookSerializer'
 });
-
 ```
-## Resource Creation
-There are multiple ways that you can set up new resources in your application.
-
-### railsResourceFactory
-Similar to $resource, we provide a <code>railsResourceFactory(config)</code> function that takes a config object with the configuration
-settings for the new resource.  The factory function returns a new class that is extended from RailsResource.
-
-### RailsResource extension
-We also expose the RailsResource as base class that you can extend to create your own resource classes.  Extending the RailsResource class
-directly gives you a bit more flexibility to add custom constructor code.  There are probably ten different ways to extend the class but
-the two that we intend to be used are through CoffeeScript or through the same logic that the factory function uses.
-
-#### CoffeeScript
-````coffeescript
-class Book extends RailsResource
-  @configure url: '/books', name: 'book'
 
-class Encyclopedia extends Book
-  @configure url: '/encyclopedias', name: 'encyclopedia'
-````
-
-#### JavaScript
-Since the purpose of exposing the RailsResource was to allow for CoffeeScript users to create classes from it the JavaScript way
-is basically just the same as the generated CoffeeScript code.  The <code>RailsResource.extend</code> function is a modification
-of the <code>__extends</code> function that CoffeeScript generates.
-
-````javascript
-function Resource() {
-    Resource.__super__.constructor.apply(this, arguments);
-}
-
-RailsResource.extend(Resource);
-Resource.configure(config);
-````
 
 ### Config Options
 
 The following configuration options are available for customizing resources.  Each of the configuration options can be passed as part of an object
-to the <code>railsResourceFactory</code> function or to the resource's <code>configure</code> function.
+to the <code>railsResourceFactory</code> function or to the resource's <code>configure</code> function.  The <code>configure</code> function
+defined on the resource can be called multiple times to adjust properties as needed.
 
  * **url** - This is the url of the service.  See [Resource URLs](#resource-urls) below for more information.
  * **rootWrapping** - (Default: true) Turns on/off root wrapping on JSON (de)serialization.
@@ -186,8 +202,9 @@ to the <code>railsResourceFactory</code> function or to the resource's <code>con
          * **Accept** - application/json
          * **Content-Type** - application/json
  * **defaultParams** *(optional)* - If the resource expects a default set of query params on every call you can specify them here.
+ * **underscoreParams** *(optional)* - Controls whether or not query parameters are converted from camel case to underscore.
  * **updateMethod** *(optional)* - Allows overriding the default HTTP method (PUT) used for update.  Valid values are "post", "put", or "patch".
- * **serializer** *(optional)* - Allows specifying a custom [serializer](#serializers) allow configuring custom serialization options.
+ * **serializer** *(optional)* - Allows specifying a custom [serializer](#serializers) to configure custom serialization options.
  * **requestTransformers** *(optional) - See [Transformers / Interceptors](#transformers--interceptors)
  * **responseInterceptors** *(optional)* - See [Transformers / Interceptors](#transformers--interceptors)
  * **afterResponseInterceptors** *(optional)* - See [Transformers / Interceptors](#transformers--interceptors)
@@ -200,10 +217,11 @@ For example, you should specify "publishingCompany" and "publishingCompanies" in
 The individual resource configuration takes precedence over application-wide default configuration values.
 Each configuration option listed is exposed as a method on the provider that takes the configuration value as the parameter and returns the provider to allow method chaining.
 
-* rootWrapping - {function(boolean):railsSerializerProvider}
-* httpConfig - {function(object):railsSerializerProvider}
-* defaultParams - {function(object):railsSerializerProvider}
-* updateMethod - {function(boolean):railsSerializerProvider}
+* rootWrapping - {function(boolean):RailsResourceProvider}
+* httpConfig - {function(object):RailsResourceProvider}
+* defaultParams - {function(object):RailsResourceProvider}
+* underscoreParams - {function(boolean):RailsResourceProvider}
+* updateMethod - {function(boolean):RailsResourceProvider}
 
 For example, to turn off the root wrapping application-wide and set the update method to PATCH:
 
@@ -247,6 +265,10 @@ RailsResources have the following class methods available.
 
 * configure(options) - Change one or more configuration option for a resource.
 
+* extendTo(child) - Modifies the child to be a subclass of a RailsResource.  This can be used to create multiple levels of inheritance. See [RailsResource extension](#RailsResource-extension) for more information
+
+* include(...module) - Includes a mixin module into the resource.  See [Mixins](#mixins) for more information
+
 * setUrl(url) - Updates the url for the resource, same as calling <code>configure({url: url})</code>
 
 * $url(context, path) - Returns the resource URL using the given context with the optional path appended if provided.
@@ -441,6 +463,119 @@ The resource also exposes a class method <code>afterResponse(fn)</code> that acc
 to the list of after response interceptors for the resource class.  Functions added with <code>afterResponse</code> don't need to know anything about promises since they are automatically wrapped
 as an interceptor.
 
+## Mixins
+The ability to add a [Mixin](http://en.wikipedia.org/wiki/Mixin) to a RailsResource is modeled after the example code in
+in the [Classes](http://arcturo.github.io/library/coffeescript/03_classes.html) chapter of [The Little Book on CoffeeScript](http://arcturo.github.io/library/coffeescript/index.html).
+
+RailsResource provides two methods:
+* **extend** - Add class properties / methods to the resource
+* **include** - Add instance properties / methods to the resource prototype chain
+
+When you call <code>extend</code> or <code>include</code> the mixin will be added to the resource.  If your mixin provides
+one of the callback methods (<code>extended</code> or <code>included</code>) then those methods will be called when the mixin
+is added.  One additional change from the normal mixin behavior is that your mixins can implement an additional <code>configure</code>
+function that will be called whenever the resource's <code>configure</code> function is called.  That way the mixin can provide
+additional configuration options.
+
+## Extensions
+Extensions are provided [mixins](#mixins) that follow specific naming pattern to make it easier to include them by a shortened name.
+
+The available extension names are:
+ * [snapshots](#snapshots) - RailsResourceSnapshotsMixin
+
+To include an extension, you have to first include the extension in your project.
+You then need to add the extension to the in one of the following ways to RailsResource:
+
+### Application-wide Resource Extensions
+<code>RailsResourceProvider.extensions</code> - adds the extension to all RailsResources within the application.
+````javascript
+app.config(function (RailsResourceProvider) {
+    RailsResourceProvider.extensions('snapshots');
+});
+````
+
+### Per-Resource Extensions
+#### Configuration Option
+The <code>extensions</code> configuration option adds the extension to a single RailsResource
+
+##### JavaScript
+````javascript
+Book = railsResourceFactory({
+    url: '/books',
+    name: 'book',
+    extensions: ['snapshots']
+});
+````
+##### CoffeeScript
+````coffeescript
+class Book extends RailsResource
+  @configure url: '/books', name: 'book', extensions: ['snapshots']
+````
+
+#### RailsResource.extend
+RailsResource.extend - explicitly include the extension as a module
+
+##### JavaScript
+````javascript
+Book = railsResourceFactory({ url: '/books', name: 'book' });
+// by name
+Book.extend('RailsResourceSnapshotsMixin');
+// or by injected reference
+Book.extend(RailsResourceSnapshotsMixin);
+````
+
+##### CoffeeScript
+
+````coffeescript
+class Book extends RailsResource
+  @configure url: '/books', name: 'book'
+  @extend 'RailsResourceSnapshotsMixin'
+````
+
+### Snapshots
+Snapshots allow you to save off the state of the resource at a specific point in time and if need be roll back to one of the
+saved snapshots and yes, you can create as many snapshots as you want.
+
+Snapshots serialize the resource instance and save off a copy of the serialized data in the <code>$snapshots</code> array on the instance.
+If you use a custom serialization options to control what is sent to the server you may want to consider whether or not you want to use
+different serialization options.  If so, you can specify an specific serializer for snapshots using the <code>snapshotSerializer</code> configuration
+option.
+
+Calling <code>save</code>, <code>create</code>, <code>update</code>, or <code>delete</code>/<code>remove</code> on a resource instance
+will remove all snapshots when the operation completes successfully.
+
+#### Configuration Options
+ * **snapshotSerializer** *(optional)* - Allows specifying a custom [serializer](#serializers) to configure custom serialization options specific to [snapshot and rollback](#snapshots).
+
+
+#### Creating Snapshots
+Creating a snapshot is easy, just call the <code>snapshot</code> function.  You can pass an optional callback function to <code>snapshot</code> to perform
+additional custom operations after the rollback is complete.   The callback function is specific to each snapshot version created so make sure you pass it every
+time if it's a callback you always want called.
+
+#### Rolling back
+So you want to undo changes to the resource?  There are two methods you can use to roll back the resource to a previous snapshot version <code>rollback</code>
+and <code>rollbackTo</code>.  Each method will:
+ * Deserialize the snapshot data and update the resource instance with the new data.
+ * Remove all snapshots newer than the version being rolled back to.
+ * Call the rollback callback if it was specified on the <code>snapshot</code> in the context of the resource instance.
+
+##### rollback
+<code>rollback(numVersions)</code> allows you to roll back the resource.  If you do not specify <code>numVersions</code> then a resource is rolled back to the last
+snapshot version.  <code>numVersions</code> can be used to roll back further than the last snapshot version based on the following rules:
+
+* When <code>numVersions</code> is undefined or 0 then a single version is rolled back.
+* When <code>numVersions</code> exceeds the stored number of snapshots then the resource is rolled back to the first snapshot version.
+* When <code>numVersions</code> is less than 0 then the resource is rolled back to the first snapshot version.
+* Otherwise, <code>numVersions</code> represents the nth version from the last snapshot version (similar to calling rollback <code>numVersions</code> times).
+
+##### rollbackTo
+<code>rollbackTo(snapshotVersion)</code> allows you to roll back the resource to a specific snapshot version.
+
+* When <code>snapshotVersion</code> is greater than the number of versions then the last snapshot version will be used.
+* When <code>snapshotVersion</code> is less than 0 then the resource will be rolled back to the first version.
+* Otherwise, the resource will be rolled back to the specific version specified.
+
 ## Tests
 The tests are written using [Jasmine](http://pivotal.github.com/jasmine/) and are run using [Karma](https://github.com/karma-runner/karma).