Release api-pagination 1.0.0

Signed-off-by: David Celis <[email protected]>

Author: davidcelis

.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

.rspec

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

.travis.yml

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

Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in api_pagination.gemspec
+gemspec

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright © 2013 David Celis
+
+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.
+
+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.

README.md

@@ -0,0 +1,63 @@
+# api-pagination [![Build Status](https://travis-ci.org/davidcelis/api-pagination.png)](https://travis-ci.org/davidcelis/api-pagination)
+
+Put pagination info for your Rails API in your Link headers, not your response body.
+
+## Installation
+
+In your `Gemfile`:
+
+```ruby
+# Requires 'rails', '>= 3.0.0' and is compatible with 'rails-api'
+gem 'api-pagination'
+```
+
+## Usage
+
+In your controllers:
+
+```ruby
+class MoviesController < ApplicationController
+  after_filter only: [:index] { paginate(:movies) }
+  after_filter only: [:cast]  { paginate(:actors) }
+
+  # GET /movies
+  def index
+    @movies = Movie.page(params[:page])
+
+    render json: @movies
+  end
+
+  # GET /movies/:id/cast
+  def cast
+    @movie  = Movie.find(params[:id])
+    @actors = @movie.actors.page(params[:page])
+
+    render json: @actors
+  end
+end
+```
+
+Then `curl --include` to see your Link header pagination in action:
+
+```bash
+$ curl --include 'https://localhost:3000/movies?page=5'
+HTTP/1.1 200 OK
+Link: <http://localhost:3000/movies?page=1>; rel="first">,
+  <http://localhost:3000/movies?page=173>; rel="last">,
+  <http://localhost:3000/movies?page=6>; rel="next">,
+  <http://localhost:3000/movies?page=4>; rel="prev">
+# ...
+```
+
+api-pagination uses [Kaminari][kaminari] under the hood for paginating your ActiveRecord relations. See Kaminari's [documentation][kaminari-docs] for more information on its usage.
+
+## Contributing
+
+1. Fork it
+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
+
+[kaminari]: https://github.com/amatsuda/kaminari
+[kaminari-docs]: http://rubydoc.info/github/amatsuda/kaminari/frames

api-pagination.gemspec

@@ -0,0 +1,24 @@
+# encoding: utf-8
+$:.unshift(File.expand_path('../lib', __FILE__))
+require 'api-pagination/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'api-pagination'
+  s.version       = ApiPagination::VERSION
+  s.authors       = ['David Celis']
+  s.email         = ['[email protected]']
+  s.description   = 'Link header pagination for Rails APIs'
+  s.summary       = "Link header pagination for Rails APIs. Don't use the request body."
+  s.homepage      = 'https://github.com/davidcelis/api-pagination'
+  s.license       = 'MIT'
+
+  s.files         = Dir['lib/**/*']
+  s.test_files    = Dir['spec/**/*']
+  s.require_paths = ['lib']
+
+  s.add_dependency 'rails', '>= 3.0.0'
+  s.add_dependency 'kaminari', '>= 0.13.0'
+
+  s.add_development_dependency 'bundler', '~> 1.3'
+  s.add_development_dependency 'rspec-rails'
+end

lib/api-pagination.rb

@@ -0,0 +1,33 @@
+require 'api-pagination/version'
+require 'kaminari'
+
+module ApiPagination
+  protected
+    def paginate(scope)
+      query_params = request.query_parameters
+      scope        = instance_variable_get(:"@#{scope}")
+      url          = request.original_url.sub(/\?.*$/, '')
+      pages        = {}
+      links        = []
+
+      unless scope.first_page?
+        pages[:first] = 1
+        pages[:prev]  = scope.current_page - 1
+      end
+
+      unless scope.last_page?
+        pages[:last] = scope.total_pages
+        pages[:next] = scope.current_page + 1
+      end
+
+      pages.each do |k, v|
+        new_params = query_params.merge({ :page => v })
+        links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
+      end
+
+      headers['Link'] = links.join(', ')
+    end
+end
+
+ActionController::Base.send(:include, ApiPagination) if defined?(ActionController::Base)
+ActionController::API.send(:include, ApiPagination)  if defined?(ActionController::API)

lib/api-pagination/version.rb

@@ -0,0 +1,7 @@
+module ApiPagination
+  MAJOR = 1
+  MINOR = 0
+  PATCH = 0
+
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

spec/controllers/numbers_controller_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+describe NumbersController do
+  describe 'GET #index' do
+    context 'without enough items to give more than one page' do
+      it 'should not paginate' do
+        get :index, count: 20
+        response.headers['Link'].should be_blank
+      end
+    end
+
+    context 'with enough items to paginate' do
+      context 'when on the first page' do
+        before(:each) do
+          get :index, count: 100
+
+          @links = response.headers['Link'].split(', ')
+        end
+
+        it 'should not give a link with rel "first"' do
+          @links.should_not include('rel="first"')
+        end
+
+        it 'should not give a link with rel "prev"' do
+          @links.should_not include('rel="prev"')
+        end
+
+        it 'should give a link with rel "last"' do
+          @links.should include('<http://test.host/numbers?count=100&page=4>; rel="last"')
+        end
+
+        it 'should give a link with rel "next"' do
+          @links.should include('<http://test.host/numbers?count=100&page=2>; rel="next"')
+        end
+      end
+
+      context 'when on the last page' do
+        before(:each) do
+          get :index, count: 100, page: 4
+
+          @links = response.headers['Link'].split(', ')
+        end
+
+        it 'should not give a link with rel "last"' do
+          @links.should_not include('rel="last"')
+        end
+
+        it 'should not give a link with rel "next"' do
+          @links.should_not include('rel="next"')
+        end
+
+        it 'should give a link with rel "first"' do
+          @links.should include('<http://test.host/numbers?count=100&page=1>; rel="first"')
+        end
+
+        it 'should give a link with rel "prev"' do
+          @links.should include('<http://test.host/numbers?count=100&page=3>; rel="prev"')
+        end
+      end
+
+      context 'when somewhere comfortably in the middle' do
+        it 'should give all pagination links' do
+          get :index, count: 100, page: 2
+
+          links = response.headers['Link'].split(', ')
+
+          links.should include('<http://test.host/numbers?count=100&page=1>; rel="first"')
+          links.should include('<http://test.host/numbers?count=100&page=4>; rel="last"')
+          links.should include('<http://test.host/numbers?count=100&page=3>; rel="next"')
+          links.should include('<http://test.host/numbers?count=100&page=1>; rel="prev"')
+        end
+      end
+    end
+  end
+end
+
+
+
+
+