Deprecate as_json and array_as_json methods

README.md

@@ -45,7 +45,7 @@ class AlbumSerializer
 end
 ```
 
-`AlbumSerializer.as_json(album)` produces:
+`AlbumSerializer.as_serialized(album)` produces:
 
 ```javascript
 {
@@ -57,7 +57,7 @@ end
 }
 ```
 
-`as_json` accepts an optional `context` hash parameter which can be used by your Serializers to customize their output:
+`as_serialized` accepts an optional `context` hash parameter which can be used by your Serializers to customize their output:
 
 ```ruby
 class AlbumSerializer
@@ -75,7 +75,7 @@ end
 ```
 
 ```ruby
-AlbumSerializer.as_json(album, { admin?: true })
+AlbumSerializer.as_serialized(album, { admin?: true })
 ```
 
 ## Exposing an API
@@ -99,7 +99,7 @@ These endpoint will live at URLs such as `/albums` and `/albums/142857`:
 * http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json
 * http://restpack-serializer-sample.herokuapp.com/api/v1/albums/4.json
 
-The `AlbumSerializer` also provides a `single` method which will return a serialized resource similar to `as_json` above.
+The `AlbumSerializer` also provides a `single` method which will return a serialized resource similar to `as_serialized` above.
 
 `page`, `resource` and `single` methods take an optional scope argument allowing us to enforce arbitrary constraints:
 
@@ -381,3 +381,7 @@ end
 
 `bundle`
 `rake spec`
+
+## Deprecation Notice
+
+The `as_json` method has been renamed to `as_serialized` to more accurately represent the output of the method. In addition, the `array_as_json` method has been renamed to `array_as_serialized`. For the time being, `as_json` and `array_as_json` wrappers have been provided to prevent breaking changes, but they will be removed in the future.

lib/restpack_serializer/serializable.rb

@@ -32,10 +32,15 @@ module Serializer
 
     class InvalidInclude < Exception; end
 
+    ## Note: `as_json is deprecated. Please use `as_serialized` instead.
     def as_json(model, context = {})
+      as_serialized(model, context)
+    end
+
+    def as_serialized(model, context = {})
       return if model.nil?
       if model.kind_of?(Array)
-        return model.map { |item| as_json(item, context) }
+        return model.map { |item| as_serialized(item, context) }
       end
 
       @model, @context = model, context
@@ -91,19 +96,30 @@ def include_attribute?(name)
     module ClassMethods
       attr_accessor :model_class, :href_prefix, :key
 
+      ## NOTE: `array_as_json` has been renamed
+      ## to `array_as_serialized` and is  nowdeprecated.
       def array_as_json(models, context = {})
-        new.as_json(models, context)
+        array_as_serialized(models, context)
+      end
+
+      def array_as_serialized(models, context = {})
+        new.as_serialized(models, context = {})
       end
 
+      ## NOTE: `as_json` has been renamed to `as_serialized` and is now deprecated.
       def as_json(model, context = {})
-        new.as_json(model, context)
+        as_serialized(model,context)
+      end
+
+      def as_serialized(model, context = {})
+        new.as_serialized(model, context)
       end
 
       def serialize(models, context = {})
         models = [models] unless models.kind_of?(Array)
 
         {
-          self.key() => models.map {|model| self.as_json(model, context)}
+          self.key() => models.map {|model| self.as_serialized(model, context)}
         }
       end
 

lib/restpack_serializer/serializable/paging.rb

@@ -30,7 +30,7 @@ def page_with_options(options)
     private
 
     def serialize_page(page, options)
-      page.map { |model| self.as_json(model, options.context) }
+      page.map { |model| self.as_serialized(model, options.context) }
     end
 
     def serialize_meta(page, options)

lib/restpack_serializer/serializable/side_load_data_builder.rb

@@ -11,7 +11,7 @@ def initialize(association, models, serializer)
       def side_load_belongs_to
         foreign_keys = @models.map { |model| model.send(@association.foreign_key) }.uniq
         side_load = @association.klass.find(foreign_keys)
-        json_model_data = side_load.map { |model| @serializer.as_json(model) }
+        json_model_data = side_load.map { |model| @serializer.as_serialized(model) }
         { @association.plural_name.to_sym => json_model_data, meta: { } }
       end
 

lib/restpack_serializer/serializable/single.rb

@@ -6,7 +6,7 @@ def single(params = {}, scope = nil, context = {})
       options = RestPack::Serializer::Options.new(self, params, scope, context)
       model = options.scope_with_filters.first
 
-      return model ? self.as_json(model, context) : nil
+      return model ? self.as_serialized(model, context) : nil
     end
   end
 end

spec/serializable/attributes_spec.rb

@@ -27,10 +27,10 @@ class CustomSerializer
   describe '#transform_attributes' do
     let(:model) { OpenStruct.new(gonzaga: 'IS A SCHOOL') }
 
-    subject(:as_json) { CustomSerializer.as_json(model) }
+    subject(:as_serialized) { CustomSerializer.as_serialized(model) }
 
     it 'uses the transform method on the model attribute' do
-      expect(as_json[:gonzaga]).to eq('is a school')
+      expect(as_serialized[:gonzaga]).to eq('is a school')
     end
   end
 end

spec/serializable/serializer_spec.rb

@@ -26,8 +26,8 @@ class EmptySerializer
       include RestPack::Serializer
     end
 
-    it ".as_json serializes to an empty hash" do
-      EmptySerializer.as_json(person).should == { }
+    it ".as_serialized serializes to an empty hash" do
+      EmptySerializer.as_serialized(person).should == { }
     end
   end
 
@@ -70,9 +70,9 @@ def custom_attributes
     end
   end
 
-  describe ".as_json" do
+  describe ".as_serialized" do
     it "serializes specified attributes" do
-      serializer.as_json(person).should == {
+      serializer.as_serialized(person).should == {
         id: '123', name: 'Gavin', description: 'This is person #123',
         href: '/people/123', custom_key: 'custom value for model id 123'
       }
@@ -81,7 +81,7 @@ def custom_attributes
     context "an array" do
       let(:people) { [person, person] }
       it "results in a serialized array" do
-        serializer.as_json(people).should == [
+        serializer.as_serialized(people).should == [
           {
             id: '123', name: 'Gavin', description: 'This is person #123',
             href: '/people/123', custom_key: 'custom value for model id 123'
@@ -92,9 +92,9 @@ def custom_attributes
           }
         ]
       end
-      context "#array_as_json" do
+      context "#array_as_serialized" do
         it "results in a serialized array" do
-          serializer.class.array_as_json(people).should == [
+          serializer.class.array_as_serialized(people).should == [
             {
               id: '123', name: 'Gavin', description: 'This is person #123',
               href: '/people/123', custom_key: 'custom value for model id 123'
@@ -110,25 +110,25 @@ def custom_attributes
 
     context "nil" do
       it "results in nil" do
-        serializer.as_json(nil).should == nil
+        serializer.as_serialized(nil).should == nil
       end
     end
 
     context "with options" do
       it "excludes specified attributes" do
-        serializer.as_json(person, { include_description?: false }).should == {
+        serializer.as_serialized(person, { include_description?: false }).should == {
           id: '123', name: 'Gavin', href: '/people/123',
           custom_key: 'custom value for model id 123'
         }
       end
 
       it "excludes custom attributes if specified" do
-        hash = serializer.as_json(person, { is_admin?: false })
+        hash = serializer.as_serialized(person, { is_admin?: false })
         hash[:admin_info].should == nil
       end
 
       it "includes custom attributes if specified" do
-        hash = serializer.as_json(person, { is_admin?: true })
+        hash = serializer.as_serialized(person, { is_admin?: true })
         hash[:admin_info].should == {
           key: "super_secret_sauce",
           array: [
@@ -144,7 +144,7 @@ def custom_attributes
 
         it "includes 'links' data for :belongs_to associations" do
           @album1 = FactoryGirl.create(:album_with_songs, song_count: 11)
-          json = serializer.as_json(@album1.songs.first)
+          json = serializer.as_serialized(@album1.songs.first)
           json[:links].should == {
             artist: @album1.artist_id.to_s,
             album: @album1.id.to_s
@@ -155,7 +155,7 @@ def custom_attributes
       context "with a serializer with has_* associations" do
         let(:artist_factory) { FactoryGirl.create :artist_with_fans }
         let(:artist_serializer) { MyApp::ArtistSerializer.new }
-        let(:json) { artist_serializer.as_json(artist_factory) }
+        let(:json) { artist_serializer.as_serialized(artist_factory) }
         let(:side_load_ids) { artist_has_association.map {|obj| obj.id.to_s } }
 
         context "when the association has been eager loaded" do

spec/serializable/side_loading/belongs_to_spec.rb

@@ -38,7 +38,7 @@
 
           it "returns side-loaded albums" do
             side_loads.should == {
-              albums: [MyApp::AlbumSerializer.as_json(MyApp::Song.first.album)],
+              albums: [MyApp::AlbumSerializer.as_serialized(MyApp::Song.first.album)],
               meta: { }
             }
           end
@@ -58,8 +58,8 @@
           it "returns side-loaded albums" do
             side_loads.should == {
               albums: [
-                MyApp::AlbumSerializer.as_json(song1.album),
-                MyApp::AlbumSerializer.as_json(song2.album)
+                MyApp::AlbumSerializer.as_serialized(song1.album),
+                MyApp::AlbumSerializer.as_serialized(song2.album)
               ],
               :meta => { }
             }