Skip to content

Latest commit

 

History

History
156 lines (106 loc) · 7.41 KB

README.md

File metadata and controls

156 lines (106 loc) · 7.41 KB
Raw

ApiView

Build Status codecov.io

Object serializer with

  • small codebase
  • focus on performance
  • benchmarks are guiding the implementation
  • only MultiJson as sole dependency

The initial code was copied from chetan and wrapped into a gem with unit-tests and a bit more convenient API ( original links )

Why should you even care? Is (... insert your favourite ruby serializer ... ) not good enough?

  • you want great performance
  • you care about object allocations (less garbage to collect for the Ruby VM)
  • you want blazing fast test suite, so that you can switch globally the serialization off and test just the shape of the resulting Hash object -> no converting to JSON, then parsing JSON back and checking values on it, that sux!
  • really small and clean codebase
  • zero dependencies (NO ACTIVESUPPORT!), but you should use MultiJson + OJ for best performance.
  • unit-tested and with 100% test coverage

ApiView gives you all that and stays very small doing that.

Installation

## Add this line to your application's Gemfile:
gem 'api_view'


## And then execute:
$ bundle

Usage

  • you inherit from ApiView::Base

  • you say, what model should be serialized by default with this serializer (optional)

  • you specify an array of attributes, that will be copied from the object in serializer

  • you tell how you main object is called (defaults to object / obj)

  • you implement instance_convert-method for further customization of the serialization -> field - a setter method, that also accepts via: SomeSerializerApiView

    class EventApiView < EventSummaryApiView
  # default serializer for BoxScore, will be picked, if none other was given
  for_model ::Event

  # the attributes to copy from the object
  attributes :share_url, :sport_name

  # the name of your main object, optional
  main_object :event

  # the method to add additional logic + fields
  def instance_convert
    # just a setter method with optional serializer for that sub-object
    field :box_score, event.box_score, via: BasketballBoxScoreApiView
  end
end




## a more complete example
class Event
  attr_accessor :game_date, :game_type, :status
end

class EventSerializer < ::ApiView::Base
  attributes :game_date, :game_type, :status
  main_object :event
  for_model ::Event

  # this is your chance to do extra work
  def instance_convert
    field :away_team,  "any value here"
  end
end

e = Event.new; e.game_date = Time.now; e.game_type = 'baseball'; e.status = 'won'
EventSerializer.render(e)

# because we configured the mapping from serializer to a Ruby class, this also works:
ApiView::Engine.render(e)

For more examples take a look into the example/-folder and run the benchmark script via ruby example/benchmark.rb.

Developement

# run tests
$ sh/test

Contributing

  1. Fork it ( https://github.com/mindframer/api_view/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Benchmark numbers (ApiView vs the rest of the pack)

                                              user     system      total        real       allocations      memsize
RABL Ultra Simple                         4.860000   0.620000   5.480000 (  5.493406)              664        25787
AMS Ultra Simple                          0.220000   0.000000   0.220000 (  0.220079)               26          650
Presenters Ultra Simple                   0.140000   0.000000   0.140000 (  0.152729)               24          650
ApiView Ultra Simple                      0.190000   0.000000   0.190000 (  0.193124)               12          842
-------------------------------------------------------------------------------------------------------------------
RABL Simple                              21.470000   3.330000  24.800000 ( 25.147988)             2265       114051
AMS Simple                                1.060000   0.000000   1.060000 (  1.066668)              105         2726
Presenters Simple                         0.610000   0.000000   0.610000 (  0.611980)               98         2918
ApiView Simple                            0.280000   0.010000   0.290000 (  0.292290)               17         2246
-------------------------------------------------------------------------------------------------------------------
RABL Complex                             43.930000   6.850000  50.780000 ( 51.574975)             4325       248000
AMS Complex                               2.150000   0.000000   2.150000 (  2.160445)              209         5851
Presenters Complex                        1.210000   0.010000   1.220000 (  1.220806)              201         7395
ApiView Complex                           0.270000   0.000000   0.270000 (  0.270517)               21         1504


Collection tests:

                                              user     system      total        real       allocations      memsize
RABL Ultra Simple: Collection             3.560000   0.600000   4.160000 (  4.182852)            43102      1977224
AMS Ultra Simple: Collection              0.120000   0.000000   0.120000 (  0.124631)             1914        47786
Presenters Ultra Simple: Collection       0.100000   0.010000   0.110000 (  0.109781)             3508        67594
ApiView Ultra Simple: Collection          0.050000   0.000000   0.050000 (  0.050875)              311        46986
-------------------------------------------------------------------------------------------------------------------
RABL Simple: Collection                  18.720000   3.150000  21.870000 ( 21.924020)           202905     11255130
AMS Simple: Collection                    0.870000   0.010000   0.880000 (  0.890479)             9714       236186
Presenters Simple: Collection             0.540000   0.000000   0.540000 (  0.542100)            16108       380794
ApiView Simple: Collection                0.160000   0.000000   0.160000 (  0.166484)              812       187386
-------------------------------------------------------------------------------------------------------------------
RABL Complex: Collection                 41.190000   6.680000  47.870000 ( 48.438854)           408015     25251570
AMS Complex: Collection                   2.170000   0.030000   2.200000 (  2.211721)            20114       548686
Presenters Complex: Collection            1.380000   0.010000   1.390000 (  1.389608)            34408       960494
ApiView Complex: Collection               0.150000   0.000000   0.150000 (  0.145595)             1212       113186

Original links: