Paginater

A wannabe pagination gem for Grape

YAPG: Yet another pagination gem...

Paginater is a simple (still work in progress) gem that want to be a little utility when your API is dealing with a collection of objects.

You can use Paginater in your Grape app to have a simple feature of pagination that understand page and size parameters in a GET route.

Installation

Add this line to your application's Gemfile:

gem 'paginater'

And then execute:

$ bundle

Or install it yourself as:

$ gem install paginater

Usage

Paginater (actually) supports 3 pagination systems:

:simple
:kaminari
:wrapper

The :simple option uses only the core library functions of Ruby; the :kaminari option delegates the pagination to the powerful gem Kaminari and the :wrapper gives you the possibility to wrap your content in a convenient object (this feature is work in progress). Paginater also provides with each response, headers useful for pagination.

Enable Paginater makes the API url aware of the page parameter (required) and the size parameter (optional).

Tell your API to use Paginater:

class API < Grape:API
  format :json
  formatter :json, Grape::Formatter::Paginater

  # ...

  get '/stuff', :paginater => :simple do
    # ... your stuff
  end

end

And get the content paginated with:

/stuff?page=1 and /stuff?page=1&size=4

Use Kaminari gem:

class API < Grape:API
  format :json
  formatter :json, Grape::Formatter::Paginater

  # ...

  get '/users', :paginater => :kaminari do
    User.where("age > 18")
  end

end

Using :kaminari gives more flexibilty and don't raise any error when an exceeding page is required.

With a :size greater than the total_count will be returned and diplayed all the items in the resource.

Paginater also provide in the headers (see the examples) links useful for pagination. Another feature in progress is the possibility to wrap your content in a convenient object; maybe in the future will be possible to associate with this object a specific template... Set this option (if you dare) with: :paginater => :wrapper

class API < Grape:API
  format :json
  formatter :json, Grape::Formatter::Paginater

  # ...

  get '/stuff', :paginater => :wrapper do
    # ... your stuff
  end

end

Browse the spec directory and spec/paginater/paginater_spec.rb or spec/paginater/paginater_with_kaminari_spec.rb files for more examples.

The last feature in progress is something useful stored in cookies. Actually you can find a value: #page/#pages/#count calculated with size=1.

A Running Test

In the test directory there is a very simple running test (configured with the :kaminari option).

$ cd test
/test$ bundle exec rackup
[2013-03-09 16:05:25] INFO  WEBrick 1.3.1
[2013-03-09 16:05:25] INFO  ruby 2.0.0 (2013-02-24) [i686-linux]
[2013-03-09 16:05:25] INFO  WEBrick::HTTPServer#start: pid=3776 port=9292
   ...

This expose two resources: /foo and /news (the last require an internet connection). Then try:

http://localhost:9292/foo?page=1
  ["Alpha"]

http://localhost:9292/foo?page=4&size=6
  ["Sierra","Tango","Uniform","Victor","Whiskey","X-Ray"]

http://localhost:9292/foo?page=2&size=4
  ["Echo","Foxtrot","Golf","Hotel"]

http://localhost:9292/foo
  {"error":"missing param"}

http://localhost:9292/foo?page=42
  [] #=> with :kaminari
  #=> {"error":"invalid page 42"} # with :simple

http://localhost:9292/foo?page=2&size=42
  [] #=> with :kaminari
  #=> {"error":"page 2 out"} # with :simple

http://localhost:9292/foo?page=1&size=111
  ["Alpha","Bravo","Charlie", <...> ,"X-Ray","Yankee","Zulu"]

http://localhost:9292/foo?page=1&size=0
  #=> no error because default size is 1
  #=> {"error":"divided by 0"}   # with :kaminari
  #=> {"error":"invalid size 0"} # with :simple

http://localhost:9292/foo?page=0
  {"error":"first page must be 1"}

headers

In the response header there are links useful for pagination... maybe more to come...

first page: {:url=>\"/foo?page=1\", :rel=>\"first\"};{:url=>\"/foo?page=2\", :rel=>\"next\"}\n
last page: {:url=>\"/foo?page=1\", :rel=>\"first\"};;{:url=>\"/foo?page=9\", :rel=>\"prev\"}
just a page: {:url=>\"/foo?page=1&size=3\", :rel=>\"first\"};{:url=>\"/foo?page=4&size=3\", :rel=>\"next\"};{:url=>\"/foo?page=2&size=3\", :rel=>\"prev\"}

The first page:

$ curl -I http://localhost:9292/foo?page=1&size=4
$ HTTP/1.1 200 OK 
Content-Type: application/json
Link: {:url=>"/foo?page=1", :rel=>"first"};{:url=>"/foo?page=2", :rel=>"next"}
Content-Length: 9
Server: WEBrick/1.3.1 (Ruby/2.0.0/2013-02-24)
Date: Sat, 09 Mar 2013 15:21:10 GMT
Connection: Keep-Alive

$ curl -I http://localhost:9292/news?page=1&size=1
$ HTTP/1.1 200 OK 
Content-Type: application/json
Link: {:url=>"/news?page=1", :rel=>"first"};{:url=>"/news?page=2", :rel=>"next"}
Content-Length: 130
Server: WEBrick/1.3.1 (Ruby/2.0.0/2013-02-24)
Date: Sat, 09 Mar 2013 16:56:15 GMT
Connection: Keep-Alive

Just a page:

$ curl -I http://localhost:9292/foo?page=2&size=4
$ HTTP/1.1 200 OK 
Content-Type: application/json
Set-Cookie: 2/26/26
Link: {:url=>"/foo?page=1", :rel=>"first"};{:url=>"/foo?page=3", :rel=>"next"};{:url=>"/foo?page=1", :rel=>"prev"}
Content-Length: 9
Server: WEBrick/1.3.1 (Ruby/2.0.0/2013-02-24)
Date: Sat, 09 Mar 2013 15:22:12 GMT
Connection: Keep-Alive

The last page:

$ curl -I http://localhost:9292/foo?page=26
$ HTTP/1.1 200 OK 
Content-Type: application/json
Set-Cookie: 26/26/26
Link: {:url=>"/foo?page=1", :rel=>"first"};;{:url=>"/foo?page=25", :rel=>"prev"} 
Content-Length: 8
Server: WEBrick/1.3.1 (Ruby/2.0.0/2013-02-24)
Date: Sat, 09 Mar 2013 15:23:03 GMT
Connection: Keep-Alive

$ curl -I http://localhost:9292/news?page=10
$ HTTP/1.1 200 OK 
Content-Type: application/json
Set-Cookie: 10/10/10
Link: {:url=>"/news?page=1", :rel=>"first"};{:url=>"/news?page=9", :rel=>"prev"}
Content-Length: 127
Server: WEBrick/1.3.1 (Ruby/2.0.0/2013-02-24)
Date: Sat, 09 Mar 2013 16:56:47 GMT
Connection: Keep-Alive

With :simple

$ curl -I http://localhost:9292/news?page=11
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 27
Connection: keep-alive
Server: thin 1.5.0 codename Knife

With :kaminari

#=> []
HTTP/1.1 200 OK

Note

Unrelated but inspired by this beautiful code:

Discuss

There is a thread on the grape-mailinglist:

https://groups.google.com/forum/?fromgroups=#!topic/ruby-grape/vH2DP1qsN9I

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request