skip to content

In a Rails API controller using Pagy 43, how do headers_hash, data_hash and client_limit expose pagination metadata and let a client choose its page size?

level: middleimportance: should knowfreq 28%

answer

  1. merge into response.headers
  2. current-page, page-limit, total-count, total-pages
  3. data_keys: picks the fields
  4. client_limit: caps ?limit=
  5. page_url(:next) is nil on the last page

basics

~10 s

@pagy.headers_hash returns a link header plus current-page, page-limit, total-count and total-pages to merge into response.headers; @pagy.data_hash returns selected numbers and URLs for a JSON body; client_limit: caps a ?limit= request.

solid answer

~40 s

After `@pagy, @events = pagy(:offset, scope, client_limit: 100)`, `response.headers.merge!(@pagy.headers_hash)` adds a `link` header with absolute `first`, `prev`, `next` and `last` URLs where they exist, plus `current-page`, `page-limit`, `total-count` and `total-pages`. `headers_map:` renames them, and `false` drops one. For a JSON body, `@pagy.data_hash(data_keys: %i[page limit count next_url])` returns just those keys, and keys whose value is nil are left out. `client_limit: 100` makes Pagy read `?limit=` and silently cap it at 100; without it the param is ignored. What you get depends on the paginator: `:countless` has no count, so totals and the `last` link disappear, and `:keyset` gives only `first` and `next`. `@pagy.page_url(:next)` returns nil on the last page.

code

ruby · 12 lines
ruby
class Api::BaseController < ActionController::API
  include Pagy::Method
  after_action { response.headers.merge!(@pagy.headers_hash) if @pagy }
end

class Api::ProductsController < Api::BaseController
  def index
    @pagy, @products = pagy(:countish, Product.order(:id), client_limit: 100, ttl: 300)
    render json: { products: @products,
                   pagination: @pagy.data_hash(data_keys: %i[page limit count next_url]) }
  end
end

go deeper

for a junior

Know that headers_hash returns pagination headers to merge into response.headers, and that data_hash returns a Hash for a JSON body.

for a middle

Explain the default header names, how data_keys: trims data_hash, and how client_limit: and limit_key: govern a client-chosen page size.

for a senior

Match the paginator to what clients really need, and keep the header names stable across the Pagy 9 to 43 upgrade.

for a principal

Decide which list endpoints promise totals, how large a page a client may request, and how renaming a header is rolled out to API consumers.

## Two ways to ship the metadata A JSON list endpoint has to tell its client where the next page is and, optionally, how many items exist. Pagy 43 offers two helpers on the pagination object. Which wire format to choose is the REST pagination topics' subject; the JSON rendering itself is the API topics' subject. This answer covers what Pagy itself produces. ## `headers_hash`: response headers ```ruby class Api::AuditEventsController < ApplicationController def index @pagy, @events = pagy(:offset, AuditEvent.order(id: :desc), client_limit: 100) response.headers.merge!(@pagy.headers_hash) render json: @events end end ``` `headers_hash` returns a Hash with lowercase names, following Rack 3's header casing: | key | value on page 3 of 1,000 events, limit 20 | |---|---| | `link` | `<https://host/api/audit_events?page=1>; rel="first", ...prev, ...next, ...last` (absolute URLs) | | `current-page` | `"3"` | | `page-limit` | `"20"` | | `total-count` | `"1000"` | | `total-pages` | `"50"` | - `headers_map: { page: 'current-page', limit: 'per-page', count: 'total', pages: false }` renames headers, and `false` drops one. - The default limit header is `page-limit`; Pagy 9's was `page-items`. - Pagy's docs suggest `after_action { response.headers.merge!(@pagy.headers_hash) if @pagy }` in a base API controller, so no action forgets it. ## `data_hash`: a Hash for the body `data_hash` returns whichever pagination facts you name: - **URLs**: `url_template`, `first_url`, `previous_url`, `current_url` (alias `page_url`), `next_url`, `last_url`. - **Numbers**: `count`, `page`, `limit`, `last`, `in`, `from`, `to`, `previous`, `next`. - **Others**: `options` and `series`. With no argument it returns the full default list, which includes the options hash. **Pass `data_keys:`** (per call or in `Pagy::OPTIONS`) to send only what clients need. Keys whose value is nil, such as `next_url` on the last page, are left out. An unknown key raises `Pagy::OptionError`. ```ruby render json: { events: @events, pagination: @pagy.data_hash(data_keys: %i[page limit count next_url]) } ``` ## Letting the client choose the size 1. By default Pagy **ignores** `?limit=` and uses the configured `limit` (20 unless changed). 2. `client_limit: 100` turns the param on. `?limit=50` gives 50 rows, `?limit=500` is **silently capped** at 100, and `?limit=0` or a non-number falls back to the default. 3. `limit_key: 'per_page'` renames the param. Links Pagy builds then carry the chosen limit, so the client keeps its size while paging. `client_limit` arrived in Pagy 43.6.3. The interim names `:max_limit` and `:client_max_limit` still work in 43.7 but print deprecation warnings. ## What each paginator can report | paginator | totals in headers | `link` relations | |---|---|---| | `:offset`, `:countish` | `total-count`, `total-pages` | first, prev, next, last | | `:countless` | none (`count` is nil) | first, prev, next | | `:keyset` | none | first, next | ## Several lists, or JSON:API style params - `root_key: 'events'` nests the params, as in `events[page]=2&events[limit]=50`, so two paginated collections in one response or request do not collide. - `jsonapi: true` forces the root key to `page`, so the params nest under `page[...]`. `urls_hash` then returns a `:prev` key instead of `:previous`, as the JSON:API specification requires. - `@pagy.urls_hash` returns just the `first`/`previous`/`next`/`last` URLs, which suits a `links` object in a response body. Two more details: - `@pagy.page_url(:next)` returns **nil** on the last page, and `page_url(:first)` returns the URL without a page param. - `absolute: true` gives full URLs from `page_url` and `data_hash`; `headers_hash` always uses absolute URLs.

  • Why might the API team prefer :countless or :keyset for this endpoint even though headers_hash then lacks total-count?
    Totals cost a `COUNT(*)` per request on `:offset`, which is significant on large tables, and many clients only follow `next`. `:countless` drops the count and keeps numeric pages, while `:keyset` drops both count and offset. The trade is explicit: clients lose `total-count`, `total-pages` and the `last` link.
  • What happens if the client sends ?limit=50 and the action does not set client_limit?
    Pagy ignores the param and serves the configured limit, 20 by default. Request#resolve_limit only reads the `limit` key when `client_limit` is truthy, so a client cannot raise the page size unless the app opts in.

  • Says ?limit=500 with client_limit: 100 raises Pagy::OptionError.
  • Believes Pagy honours ?limit= by default, without client_limit:.
  • Returns data_hash without data_keys:, sending clients every default key including options.
  • Expects total-count in headers_hash on a :countless or :keyset page.
  • Uses pagy_headers(@pagy) from Pagy 9 in a Pagy 43 controller.

Assumes Pagy 43.7 on Rails 8.1; client_limit: replaced :max_limit and :client_max_limit in 43.6.3, and Pagy 43 renamed pagy_headers and pagy_metadata to headers_hash and data_hash.