Grape::Kaminari

kaminari paginator integration for grape API framework.

Installation

Add this line to your application's Gemfile:

gem 'grape-kaminari'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-kaminari

Usage

class MyApi < Grape::API
  # Include Grape::Kaminari module in your api
  include Grape::Kaminari

  resource :posts do
    desc 'Return a list of posts.'

    # Annotate action with `paginate`.
    # This will add three optional params: page, per_page, and offset
    #
    # You can optionally overwrite the default :per_page setting (10)
    # and the :max_per_page(false/disabled) setting which will use a validator to
    # check that per_page is below the given number.
    #
    # You can disable the offset parameter from appearing in the API
    # documentation by setting it to false.
    #
    paginate per_page: 20, max_per_page: 30, offset: 5

    get do
      posts = Post.where(...)

      # Use `paginate` helper to execute kaminari methods
      # with arguments automatically passed from params
      posts, pagination  = paginate(posts)
      {posts: posts}.merge!(pagination)
      # RESULT
      # {
      #    posts: [item, item, item, item],
      #    pagination: {
      #      'X-Total': '200',
      #      'X-Total-Pages': '20',
      #      'X-Per-Page': '10',
      #      'X-Page': '1',
      #      'X-Next-Page': '2',
      #      'X-Prev-Page': ,
      #      'X-Offset': ,
      #    }
      #  }
    end

    get do
      things = ['a', 'standard', 'array', 'of', 'things', '...']

      # Use `Kaminari.paginate_array` method to convert the array
      # into an object that can be passed to `paginate` helper.
      paginate(Kaminari.paginate_array(things))
    end
  end
end

Now you can make a HTTP request to your endpoint with the following parameters

• page: your current page (default: 1)
• per_page: how many to record in a page (default: 10)
• offset: the offset to start from (default: 0)

curl -v http://host.dev/api/posts?page=3&offset=10

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/teamon/tesla.