Follow-up to QUERY: querying the collection URI itself

rubyonrails-core
1

#57973 left resources integration out of scope, and the routing guide shows this as the form apps will use:

resources :products do
  query :search, on: :collection
end
# QUERY /products/search  →  products#search

That matches get :search, on: :collection. It is the right shape when search is its own action.

RFC 10008 QUERY targets a resource and carries the query in the body. For a collection, the resource is /products, not /products/search. The extra path segment is the old “action in the URL” pattern.

query :index already does the RFC-shaped thing, because index is a canonical action and does not append a segment:

resources :products do
  query :index, on: :collection
end
# QUERY /products  →  products#index
# GET   /products  →  products#index

I only found this by drawing routes. The guide never mentions it, and query :index reads like a new action named index, not “accept QUERY on this collection.”

A small naming quirk: the resource block runs before the default get :index, so products_path attaches to the QUERY route in bin/rails routes. The helper still generates /products; GET just does not own the name.

Two asks, neither of them “make every resources index accept QUERY”:

  1. Docs. In the routing guide, next to query :search, show query :index, on: :collection as the way to QUERY the collection URI and reuse #index. That is the whole of a useful change if you want to stop there.

  2. Opt-in resources integration (the hole #57973 left). Same idea as patch + put on update, but not on by default:

    resources :products, query: true

    Draw it in the default collection block, after get :index, so the helper stays on GET:

    collection do
  get   :index if parent_resource.actions.include?(:index)
  query :index if parent_resource.query?
  post  :create if parent_resource.actions.include?(:create)
end

Not asking to add QUERY to every index. Most collections will never see the verb, rails routes would get noisier, and it fights the guide’s “search is a named collection action.” Puma still 501s QUERY until supported_http_methods is extended; unused routes would not change that, they would just sit there.

Happy to send a docs PR for (1) either way. (2) only if this shape is wanted.