bsm/grape-pagy

Grape::Pagy

Pagy pagination for grape API framework.

Installation

Add this line to your application's Gemfile:

gem 'grape-pagy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-pagy

Usage

class MyApi < Grape::API
  # Include helpers in your API.
  helpers Grape::Pagy::Helpers

  resource :posts do
    desc 'Return a list of posts.'
    params do
      # This will add two optional params: :page and :items.
      use :pagy
    end
    get do
      posts = Post.all.order(created_at: :desc)
      pagy(posts)
    end
  end

  resource :strings do
    desc 'Supports arrays as well as relations.'
    params do
      # Override defaults by setting Pagy::DEFAULT or by passing options.
      use :pagy,
          items_param: :per_page, # Accept per_page=N param to limit items.
          items: 2,               # If per_page param is blank, default to 2.
          max_items: 10           # Restrict per_page to maximum 10.
    end
    get do
      words = %w[this is a plain array of words]
      pagy(words)
    end
  end
end

Example request:

curl -si http://localhost:8080/api/posts?page=3&items=5

The response will be paginated and also will include the following headers:

Current-Page: 3
Page-Items: 5
Total-Count: 22
Total-Pages: 5
Link: <http://localhost:8080/api/posts?page=1&items=5>; rel="first", <http://localhost:8080/api/posts?page=4&items=5>; rel="next", <http://localhost:8080/api/posts?page=2&items=5>; rel="prev", <http://localhost:8080/api/posts?page=5&items=5>; rel="last"),

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bsm/grape-pagy.

grape-pagy's Issues

max_page - no information provided to the end user

First -- thanks for the great plugin. Super easy to use.

Following on from #8 - there is no way for the user to know what the max_items is set to.

So if it defaults to per_page=10 and the max is also 10 and a user puts in per_page=20. There isn't anyway they can know this was invalid.

Since no error is returned, I would suggest that the max_page value automatically be added to the description of per page.

Alternatively, there should be a way to overwrite the default description value.

Unable to start

Hi :-)

Thank you very much for grape-pagy, this is very handy ! 👍

I'm trying to use grape-pagy with pagy 6.x but it fails to start with the following error:

/home/app/.gem/ruby/3.1.2/gems/grape-pagy-0.5.1/lib/grape/pagy.rb:35:in `block in <module:Helpers>': undefined method `delete' for nil:NilClass (NoMethodError)
        items = opts.delete(:items) || ::Pagy::DEFAULT[:items]

Not throwing validation error: When max_items set

In an endpoint, max_items set to 10. It should have to throw the error if endpoint parms contain items value large than max_items

params do
      use :pagy,
          max_items: 10
 end

Expected:

{
    "error": {
        "status": 422,
        "message": "max_items value max can be 10"
    }
}

Deprecation Warnings

Not sure if it is my specific implementation, but I'm getting deprecation warnings when I run rspec. It would seem that we are using the double splat operator, but the code that calls the params does not pass the double splat.

/home/jchan/.rbenv/versions/2.7.1/lib/ruby/gems/2.7.0/gems/grape-1.6.2/lib/grape/dsl/parameters.rb:67: warning: Using the last argument as keyword parameters is deprecated; maybe ** should be added to the call
/home/jchan/.rbenv/versions/2.7.1/lib/ruby/gems/2.7.0/gems/grape-pagy-0.3.1/lib/grape/pagy.rb:34: warning: The called method is defined here

      params :pagy do |items: nil, page: nil, **opts|
        items ||= ::Pagy::VARS[:items]
        page ||= ::Pagy::VARS[:page]
        page_param = opts[:page_param] || ::Pagy::VARS[:page_param]
        items_param = opts[:items_param] || ::Pagy::VARS[:items_param]

        @api.route_setting(:pagy_options, opts)
        optional page_param, type: Integer, default: page, desc: 'Page offset to fetch.'
        optional items_param, type: Integer, default: items, desc: 'Number of items to return per page.'
      end

      def use(*names)
        named_params = @api.namespace_stackable_with_hash(:named_params) || {}
        options = names.extract_options!
        names.each do |name|
          params_block = named_params.fetch(name) do
            raise "Params :#{name} not found!"
          end
          instance_exec(options, &params_block)
        end
      end