Module: APIHelper::Sortable

Extended by:
ActiveSupport::Concern
Defined in:
lib/api_helper/sortable.rb

Overview

Helper To Make Resource APIs Sortable

A Sortable Resource API gives the flexibility to change how the returned data is sorted to the client. Clients can use the sort URL parameter to control how the returned data is sorted, as this example:

GET /posts?sort=-created_at,title

This means to sort the data by its created time descended and then the title ascended.

Usage

Include this Concern in your Action Controller:

SamplesController < ApplicationController
  include APIHelper::Sortable
end

or in your Grape API class:

class SampleAPI < Grape::API
  include APIHelper::Sortable
end

then use the sortable method like this:

resources :posts do
  get do
    sortable default_order: { created_at: :desc }
    # ...
    @posts = Post.order(sort)#...
    # ...
  end
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.sort_param_desc(example: nil, default: nil) ⇒ Object

Return the ‘sort’ param description



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/api_helper/sortable.rb', line 77

def self.sort_param_desc(example: nil, default: nil)
  if default.present?
    desc = "Specify how the returning data should be sorted, defaults to '#{default}'."
  else
    desc = "Specify how the returning data should be sorted."
  end
  if example.present?
    "#{desc} Example value: '#{example}'"
  else
    desc
  end
end

Instance Method Details

#sort ⇒ Object

Helper to get the sort data



72
73
74
 
# File 'lib/api_helper/sortable.rb', line 72

def sort
  @sort
end

#sortable(default_order: {}) ⇒ Object

Gets the ‘sort` parameter with the format ’resourses?sort=-created_at,name’, verify and converts it into an safe Hash that can be passed into the .order method.

Params:

default_order

Hash the default value to return if the sort parameter is not provided



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/api_helper/sortable.rb', line 49

def sortable(default_order: {})
  # get the parameter
  sort_by = params[:sort] || params[:sort_by]

  if sort_by.is_a? String
    # split it
    sort_by_attrs = sort_by.gsub(/[^a-zA-Z0-9\-_,]/, '').split(',')

    # save it
    @sort = {}
    sort_by_attrs.each do |attrb|
      if attrb.match(/^-/)
        @sort[attrb.gsub(/^-/, '')] = :desc
      else
        @sort[attrb] = :asc
      end
    end
  else
    @sort = default_order
  end
end