restpack_serializer 0.2.3

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+*.db
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+script: bundle exec rake test

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    restpack_serializer (0.2.3)
+      activerecord (>= 3.0)
+      activesupport (>= 3.0)
+      will_paginate (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.13)
+      activesupport (= 3.2.13)
+      builder (~> 3.0.0)
+    activerecord (3.2.13)
+      activemodel (= 3.2.13)
+      activesupport (= 3.2.13)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.13)
+      i18n (= 0.6.1)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    bump (0.4.1)
+    coderay (1.0.9)
+    database_cleaner (0.9.1)
+    diff-lcs (1.2.3)
+    factory_girl (4.2.0)
+      activesupport (>= 3.0.0)
+    ffi (1.7.0)
+    formatador (0.2.4)
+    growl (1.0.3)
+    guard (1.8.0)
+      formatador (>= 0.2.4)
+      listen (>= 1.0.0)
+      lumberjack (>= 1.0.2)
+      pry (>= 0.9.10)
+      thor (>= 0.14.6)
+    guard-rspec (2.5.4)
+      guard (>= 1.1)
+      rspec (~> 2.11)
+    i18n (0.6.1)
+    listen (1.0.0)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+      rb-kqueue (>= 0.2)
+    lumberjack (1.0.3)
+    method_source (0.8.1)
+    multi_json (1.7.2)
+    pry (0.9.12)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rake (10.0.4)
+    rb-fsevent (0.9.3)
+    rb-inotify (0.9.0)
+      ffi (>= 0.5.0)
+    rb-kqueue (0.2.0)
+      ffi (>= 0.5.0)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    slop (3.4.4)
+    sqlite3 (1.3.7)
+    thor (0.18.1)
+    tzinfo (0.3.37)
+    will_paginate (3.0.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bump
+  database_cleaner (~> 0.9.1)
+  factory_girl (~> 4.2.0)
+  growl (~> 1.0.3)
+  guard-rspec (~> 2.5.4)
+  rake (~> 10.0.3)
+  restpack_serializer!
+  rspec (~> 2.12)
+  sqlite3 (~> 1.3.7)

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :cli => "-c -f doc" do
+  watch(%r{^spec/.+_spec\.rb$}) { "spec" }
+  watch(%r{^lib/(.+)\.rb$}) { "spec" }
+  watch('spec/spec_helper.rb') { "spec" }
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Gavin Joyce and RestPack contributors.
+Copyright (c) 2011-2012 José Valim & Yehuda Katz (https://github.com/rails-api/active_model_serializers/blob/master/MIT-LICENSE.txt)
+
+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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,300 @@
+# restpack_serializer [![Build Status](https://travis-ci.org/RestPack/restpack_serializer.png?branch=master)](https://travis-ci.org/RestPack/restpack_serializer) [![Code Climate](https://codeclimate.com/github/RestPack/restpack_serializer.png)](https://codeclimate.com/github/RestPack/restpack_serializer) [![Dependency Status](https://gemnasium.com/RestPack/restpack_serializer.png)](https://gemnasium.com/RestPack/restpack_serializer) [![Gem Version](https://badge.fury.io/rb/restpack_serializer.png)](http://badge.fury.io/rb/restpack_serializer)
+
+**Model serialization, paging, side-loading and filtering**
+
+restpack_serializer allows you to quickly provide a set of RESTful endpoints for your application. It is an implementation of the emerging [JSON API](http://jsonapi.org/) standard.
+
+> [Live Demo of RestPack Serializer](http://restpack-serializer-sample.herokuapp.com/)
+
+---
+
+* [An overview of RestPack](http://goo.gl/rGoIQ)
+* [JSON API](http://jsonapi.org/)
+
+## Serialization
+
+Let's say we have an `Album` model:
+
+```ruby
+class Album < ActiveRecord::Base
+  attr_accessible :title, :year, :artist
+
+  belongs_to :artist
+  has_many :songs
+end
+```
+
+restpack_serializer allows us to define a corresponding serializer:
+
+```ruby
+class AlbumSerializer
+  include RestPack::Serializer
+  attributes :id, :title, :year, :artist_id, :href
+
+  def href
+    "/albums/#{id}.json"
+  end
+end
+```
+
+`AlbumSerializer.as_json(album)` produces:
+
+```javascript
+{
+  "id": "1",
+  "title": "Kid A",
+  "year": 2000,
+  "artist_id": 1,
+  "href": "/albums/1.json"
+}
+```
+
+## Exposing an API
+
+The `AlbumSerializer` provides `page` and `resource` method which provide paged collection and singular resource GET endpoints.
+
+```ruby
+class AlbumsController < ApplicationController
+  def index
+    render json: AlbumSerializer.page(params)
+  end
+
+  def show
+    render json: AlbumSerializer.resource(params)
+  end
+end
+```
+
+These endpoint will live at URLs such as `/albums.json` and `/albums/142857.json`:
+
+* http://restpack-serializer-sample.herokuapp.com/albums.json
+* http://restpack-serializer-sample.herokuapp.com/albums/4.json
+
+Both `page` and `resource` methods can have an optional scope allowing us to enforce arbitrary constraints:
+
+```ruby
+AlbumSerializer.page(params, Albums.where("year < 1950"))
+```
+
+## Paging
+
+Collections are paged by default. `page` and `page_size` parameters are available:
+
+* http://restpack-serializer-sample.herokuapp.com/songs.json?page=2
+* http://restpack-serializer-sample.herokuapp.com/songs.json?page=2&page_size=3
+
+Paging details are included in a `meta` attribute:
+
+http://restpack-serializer-sample.herokuapp.com/songs.json?page=2&page_size=3 yields:
+
+```javascript
+{
+    "songs": [
+        {
+            "id": "4",
+            "title": "How to Dissapear Completely",
+            "href": "/songs/4.json",
+            "links": {
+                "artist": "1",
+                "album": "1"
+            }
+        },
+        {
+            "id": "5",
+            "title": "Treedfingers",
+            "href": "/songs/5.json",
+            "links": {
+                "artist": "1",
+                "album": "1"
+            }
+        },
+        {
+            "id": "6",
+            "title": "Optimistic",
+            "href": "/songs/6.json",
+            "links": {
+                "artist": "1",
+                "album": "1"
+            }
+        }
+    ],
+    "meta": {
+        "songs": {
+            "page": 2,
+            "page_size": 3,
+            "count": 42,
+            "includes": [],
+            "page_count": 14,
+            "previous_page": 1,
+            "next_page": 3
+        }
+    },
+    "links": {
+        "songs.artists": {
+            "href": "/artists/{songs.artist}.json",
+            "type": "artists"
+        },
+        "songs.albums": {
+            "href": "/albums/{songs.album}.json",
+            "type": "albums"
+        }
+    }
+}
+```
+
+URL Templates to related data are included in the `links` element. These can be used to construct URLs such as:
+
+* /artists/1.json
+* /albums/1.json
+
+## Side-loading
+
+Side-loading allows related resources to be optionally included in a single API response. Valid side-loads can be defined in Serializers by using ```can_include``` as follows:
+
+```ruby
+class AlbumSerializer
+  include RestPack::Serializer
+  attributes :id, :title, :year, :artist_id, :href
+  can_include :songs, :artists
+
+  def href
+    "/albums/#{id}.json"
+  end
+end
+```
+
+In this example, we are allowing related `songs` and `artists` to be included in API responses. Side-loads can be specifed by using the `includes` parameter:
+
+#### No side-loads
+
+* http://restpack-serializer-sample.herokuapp.com/albums.json
+
+#### Side-load related Artists
+
+* http://restpack-serializer-sample.herokuapp.com/albums.json?includes=artists
+
+which yields:
+
+```javascript
+{
+    "albums": [
+        {
+            "id": "1",
+            "title": "Kid A",
+            "year": 2000,
+            "href": "/albums/1.json",
+            "links": {
+                "artist": "1"
+            }
+        },
+        {
+            "id": "2",
+            "title": "Amnesiac",
+            "year": 2001,
+            "href": "/albums/2.json",
+            "links": {
+                "artist": "1"
+            }
+        },
+        {
+            "id": "3",
+            "title": "Murder Ballads",
+            "year": 1996,
+            "href": "/albums/3.json",
+            "links": {
+                "artist": "2"
+            }
+        },
+        {
+            "id": "4",
+            "title": "Curtains",
+            "year": 2005,
+            "href": "/albums/4.json",
+            "links": {
+                "artist": "3"
+            }
+        }
+    ],
+    "meta": {
+        "albums": {
+            "page": 1,
+            "page_size": 10,
+            "count": 4,
+            "includes": [
+                "artists"
+            ],
+            "page_count": 1,
+            "previous_page": null,
+            "next_page": null
+        }
+    },
+    "links": {
+        "albums.songs": {
+            "href": "/songs.json?album_id={albums.id}",
+            "type": "songs"
+        },
+        "albums.artists": {
+            "href": "/artists/{albums.artist}.json",
+            "type": "artists"
+        },
+        "artists.albums": {
+            "href": "/albums.json?artist_id={artists.id}",
+            "type": "albums"
+        },
+        "artists.songs": {
+            "href": "/songs.json?artist_id={artists.id}",
+            "type": "songs"
+        }
+    },
+    "artists": [
+        {
+            "id": "1",
+            "name": "Radiohead",
+            "website": "http://radiohead.com/",
+            "href": "/artists/1.json"
+        },
+        {
+            "id": "2",
+            "name": "Nick Cave & The Bad Seeds",
+            "website": "http://www.nickcave.com/",
+            "href": "/artists/2.json"
+        },
+        {
+            "id": "3",
+            "name": "John Frusciante",
+            "website": "http://johnfrusciante.com/",
+            "href": "/artists/3.json"
+        }
+    ]
+}
+```
+
+#### Side-load related Songs
+
+* http://restpack-serializer-sample.herokuapp.com/albums.json?includes=songs
+
+An album `:has_many` songs, so the side-loads are paged. We'll be soon adding URLs to the response meta data which will point to the next page of side-loaded data. These URLs will be something like:
+
+* http://restpack-serializer-sample.herokuapp.com/songs.json?album_ids=1,2,3,4&page=2
+
+#### Side-load related Artists and Songs
+
+* http://restpack-serializer-sample.herokuapp.com/albums.json?includes=artists,songs
+
+## Filtering
+
+Simple filtering based on primary and foreign keys is possible:
+
+#### By primary key:
+
+ * http://restpack-serializer-sample.herokuapp.com/albums.json?id=1
+ * http://restpack-serializer-sample.herokuapp.com/albums.json?ids=1,2,4
+
+#### By foreign key:
+
+ * http://restpack-serializer-sample.herokuapp.com/albums.json?artist_id=1
+ * http://restpack-serializer-sample.herokuapp.com/albums.json?artist_ids=2,3
+
+Side-loading is available when filtering:
+
+ * http://restpack-serializer-sample.herokuapp.com/albums.json?artist_ids=2,3&includes=artists,songs

data/Rakefile

@@ -0,0 +1,50 @@
+require 'bump/tasks'
+require_relative 'lib/restpack_serializer/version'
+
+task :default => :test
+task :test => :spec
+
+begin
+  require "rspec/core/rake_task"
+
+  desc "Run all specs"
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = ['-cfs']
+  end
+rescue LoadError
+end
+
+namespace :test do
+  task :irb do
+    exec "irb -r ./spec/spec_helper.rb"
+  end
+end
+
+task :gem do
+  Rake::Task["gem:bump"].invoke
+  Rake::Task["gem:tag"].invoke
+  Rake::Task["gem:build"].invoke
+  Rake::Task["gem:push"].invoke
+end
+
+namespace :gem do
+  task :build do
+    sh "gem build restpack_serializer.gemspec"
+  end
+
+  task :push do
+    require 'bump'
+    sh "gem push restpack_serializer-#{Bump::Bump.current}.gem"
+  end
+
+  task :tag do
+    require 'bump'
+    version = Bump::Bump.current
+    puts "tagging v#{version}"
+    `git push && git tag v#{version} && git push --tags`
+  end
+
+  task :bump do
+    Rake::Task["bump:patch"].invoke
+  end
+end

data/lib/restpack_serializer/factory.rb

@@ -0,0 +1,16 @@
+class RestPack::Serializer::Factory
+  def self.create(*identifiers)
+    serializers = identifiers.map { |identifier| self.classify(identifier) }
+    serializers.count == 1 ? serializers.first : serializers
+  end
+
+  private
+
+  def self.classify(identifier)
+    begin
+      "#{identifier}Serializer".classify.constantize.new
+    rescue
+      "#{identifier.to_s.singularize.to_sym}Serializer".classify.constantize.new
+    end
+  end
+end

data/lib/restpack_serializer/options.rb

@@ -0,0 +1,48 @@
+module RestPack::Serializer
+  class Options
+    attr_accessor :page, :page_size, :includes, :filters, :model_class, :scope, :include_links
+
+    def initialize(model_class, params = {}, scope = nil)
+      params.symbolize_keys! if params.respond_to?(:symbolize_keys!)
+
+      @page = 1
+      @page_size = 10
+      @includes = []
+      @filters = filters_from_params(params, model_class)
+      @model_class = model_class
+      @scope = scope || model_class.send(:scoped)
+      @include_links = true
+
+      @page = params[:page].to_i if params[:page]
+      @page_size = params[:page_size].to_i if params[:page_size]
+      @includes = params[:includes].split(',').map(&:to_sym) if params[:includes]
+    end
+
+    def scope_with_filters
+      scope_filter = {}
+      @filters.keys.each do |filter|
+        value = @filters[filter]
+        if value.is_a?(String)
+          value = value.split(',')
+        end
+        scope_filter[filter] = value
+      end
+
+      @scope.where(scope_filter)
+    end
+
+    private
+
+    def filters_from_params(params, model_class)
+      serializer = RestPack::Serializer::Factory.create(model_class)
+      filters = {}
+      serializer.class.filterable_by.each do |filter|
+        [filter, "#{filter}s".to_sym].each do |key|
+          filters[filter] = params[key].split(',') if params[key]
+        end
+      end
+      filters
+    end
+
+  end
+end

data/lib/restpack_serializer/serializable/attributes.rb

@@ -0,0 +1,43 @@
+module RestPack::Serializer::Attributes
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def serializable_attributes
+      @serializable_attributes
+    end
+
+    def attributes(*attrs)
+      attrs.each { |attr| attribute attr }
+    end
+
+    def attribute(name, options={})
+      options[:key] ||= name.to_sym
+
+      @serializable_attributes ||= {}
+      @serializable_attributes[options[:key]] = name
+
+      define_attribute_method name
+      define_include_method name
+    end
+
+    def define_attribute_method(name)
+      unless method_defined?(name)
+        define_method name do
+          value = @model.send(name)
+          value = value.to_s if name == :id
+          value
+        end
+      end
+    end
+
+    def define_include_method(name)
+      method = "include_#{name}?".to_sym
+
+      unless method_defined?(method)
+        define_method method do
+          @options[method].nil? || @options[method]
+        end
+      end
+    end
+  end
+end

data/lib/restpack_serializer/serializable/paging.rb

@@ -0,0 +1,54 @@
+module RestPack::Serializer::Paging
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def page(params = {}, scope = nil)
+      page_with_options RestPack::Serializer::Options.new(self.model_class, params, scope)
+    end
+
+    def page_with_options(options)
+      page = options.scope_with_filters.paginate(
+        page: options.page,
+        per_page: options.page_size
+      )
+
+      result = {
+        self.key => serialize_page(page),
+        :meta => {
+          self.key => serialize_meta(page, options)
+        }
+      }
+
+      if options.include_links
+        result[:links] = self.links
+        Array(RestPack::Serializer::Factory.create(*options.includes)).each do |serializer|
+          result[:links].merge! serializer.class.links
+        end
+      end
+
+      side_load_data = side_loads(page, options)
+      result[:meta].merge!(side_load_data[:meta] || {})
+      result.merge side_load_data.except(:meta)
+    end
+
+    private
+
+    def serialize_page(page)
+      page.map { |model| self.as_json(model) }
+    end
+
+    def serialize_meta(page, options)
+      meta = {
+        page: options.page,
+        page_size: options.page_size,
+        count: page.total_entries,
+        includes: options.includes
+      }
+
+      meta[:page_count] = ((page.total_entries - 1) / options.page_size) + 1
+      meta[:previous_page] = meta[:page] > 1 ? meta[:page] - 1 : nil
+      meta[:next_page] = meta[:page] < meta[:page_count] ? meta[:page] + 1 : nil
+      meta
+    end
+  end
+end

data/lib/restpack_serializer/serializable/resource.rb

@@ -0,0 +1,9 @@
+module RestPack::Serializer::Resource
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def resource(params = {}, scope = nil)
+      page_with_options RestPack::Serializer::Options.new(self.model_class, params, scope)
+    end
+  end
+end