Merge pull request #548 from zendesk/fvilela/add-cbp-endpoints

[RED-1821] Cater for endpoints with CBP support

Author: fbvilela

.rubocop.yml

@@ -8,6 +8,11 @@ AllCops:
     - spec/core/middleware/response/sanitize_response_spec.rb
     - vendor/**/*
 
+# Prevents Ruby 3.1 incompatibility error. You can enable this cop when Ruby 2.7 support is dropped.
+# See https://github.com/rubocop/rubocop/issues/10258
+Layout/BlockAlignment:
+  Enabled: false
+
 # Align ends correctly.
 Layout/EndAlignment:
   EnforcedStyleAlignWith: variable

.rubocop_todo.yml

@@ -176,6 +176,7 @@ Naming/AccessorMethodName:
     - 'lib/zendesk_api/collection.rb'
     - 'lib/zendesk_api/lru_cache.rb'
     - 'lib/zendesk_api/resources.rb'
+    - 'lib/zendesk_api/pagination.rb'
 
 # Offense count: 1
 # Configuration parameters: EnforcedStyleForLeadingUnderscores.

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## v3.0.2
+
+In this version, we are adding CBP support to Tickets, Triggers, Groups, Organizations, GroupMembership and OrganizationMembership.
+The supported enpoints will benefit from CBP requests and more endpoints should be added to the list in the near future.
+
 ## v3.0.1
 
 This version introduces a small change in order to prevent CBP request attempts for API endpoints in which we know this pagination is not supported. At the moment, the show_many endpoints have been excluded from attempting CBP requests.

README.md

@@ -189,6 +189,17 @@ client.tickets.all! do |resource, page_number|
 end
 ```
 
+### Cursor Based Pagination
+
+A few endpoints related to organizations, tickets, triggers and groups will now make use of cursor based pagination by default.
+It is also recommended to use CBP whenever [the Zendesk developer documentation](https://developer.zendesk.com/api-reference) says it's supported.
+Pass `page[size]=number` in the parameters to attempt a CBP request, like the example below:
+
+```ruby
+client.connection.get('/api/v2/suspended_tickets', page: { size: 100 }).body
+{"suspended_tickets"=>[...], "meta"=>{"has_more"=>true, "after_cursor"=>" ... ", "before_cursor"=>nil}, "links"=>{"prev"=>nil, "next"=>"..."}}
+```
+
 ### Callbacks
 
 Callbacks can be added to the `ZendeskAPI::Client` instance and will be called (with the response env) after all response middleware on a successful request.

lib/zendesk_api/collection.rb

@@ -1,14 +1,14 @@
 require 'zendesk_api/resource'
 require 'zendesk_api/resources'
 require 'zendesk_api/search'
+require 'zendesk_api/pagination'
 
 module ZendeskAPI
   # Represents a collection of resources. Lazily loaded, resources aren't
   # actually fetched until explicitly needed (e.g. #each, {#fetch}).
   class Collection
-    DEFAULT_PAGE_SIZE = 100
-
     include ZendeskAPI::Sideloading
+    include Pagination
 
     # Options passed in that are automatically converted from an array to a comma-separated list.
     SPECIALLY_JOINED_PARAMS = [:ids, :only]
@@ -116,30 +116,6 @@ def count!
       @count || -1
     end
 
-    # Changes the per_page option. Returns self, so it can be chained. No execution.
-    # @return [Collection] self
-    def per_page(count)
-      clear_cache if count
-      @options["per_page"] = count
-      self
-    end
-
-    # Changes the page option. Returns self, so it can be chained. No execution.
-    # @return [Collection] self
-    def page(number)
-      clear_cache if number
-      @options["page"] = number
-      self
-    end
-
-    def first_page?
-      !@prev_page
-    end
-
-    def last_page?
-      !@next_page || @next_page == @query
-    end
-
     # Saves all newly created resources stored in this collection.
     # @return [Collection] self
     def save
@@ -323,11 +299,6 @@ def to_param
       map(&:to_param)
     end
 
-    def more_results?(response)
-      Helpers.present?(response["meta"]) && response["meta"]["has_more"]
-    end
-    alias_method :has_more_results?, :more_results? # For backward compatibility with 1.33.0 and 1.34.0
-
     def get_next_page_data(original_response_body)
       link = original_response_body["links"]["next"]
       result_key = @resource_class.model_key || "results"
@@ -344,35 +315,6 @@ def get_next_page_data(original_response_body)
 
     private
 
-    def cbp_response?(body)
-      !!(body["meta"] && body["links"])
-    end
-
-    def set_cbp_options
-      @options_per_page_was = @options.delete("per_page")
-      # Default to CBP by using the page param as a map
-      @options.page = { size: (@options_per_page_was || DEFAULT_PAGE_SIZE) }
-    end
-
-    # CBP requests look like: `/resources?page[size]=100`
-    # OBP requests look like: `/resources?page=2`
-    def cbp_request?
-      @options["page"].is_a?(Hash)
-    end
-
-    def intentional_obp_request?
-      Helpers.present?(@options["page"]) && !cbp_request?
-    end
-
-    def supports_cbp?
-      @resource_class.const_defined?(:CBP_ACTIONS) && @resource_class.const_get(:CBP_ACTIONS).any? { |supported_path| path.end_with?(supported_path) }
-    end
-
-    def first_cbp_request?
-      # @next_page will be nil when making the first cbp request
-      @next_page.nil?
-    end
-
     def get_resources(path_query_link)
       if intentional_obp_request?
         warn "Offset Based Pagination will be deprecated soon"
@@ -390,27 +332,6 @@ def get_resources(path_query_link)
       end
     end
 
-    def set_page_and_count(body)
-      @count = (body["count"] || @resources.size).to_i
-      @next_page, @prev_page = page_links(body)
-
-      if cbp_response?(body)
-        set_cbp_response_options(body)
-      elsif @next_page =~ /page=(\d+)/
-        @options["page"] = $1.to_i - 1
-      elsif @prev_page =~ /page=(\d+)/
-        @options["page"] = $1.to_i + 1
-      end
-    end
-
-    def page_links(body)
-      if body["meta"] && body["links"]
-        [body["links"]["next"], body["links"]["prev"]]
-      else
-        [body["next_page"], body["previous_page"]]
-      end
-    end
-
     def _all(start_page = @options["page"], bang = false, &block)
       raise(ArgumentError, "must pass a block") unless block
 
@@ -568,16 +489,5 @@ def assert_results(results, body)
       return if results
       raise ZendeskAPI::Error::ClientError, "Expected #{@resource_class.model_key} or 'results' in response keys: #{body.keys.inspect}"
     end
-
-    def set_cbp_response_options(body)
-      @options.page = {} unless cbp_request?
-      # the line above means an intentional CBP request where page[size] is passed on the query
-      # this is to cater for CBP responses where we don't specify page[size] but the endpoint
-      # responds CBP by default. i.e  `client.trigger_categories.fetch`
-      @options.page.merge!(
-        before: body["meta"]["before_cursor"],
-        after: body["meta"]["after_cursor"]
-                           )
-    end
   end
 end

lib/zendesk_api/pagination.rb

@@ -0,0 +1,99 @@
+module ZendeskAPI
+  class Collection
+    # Contains all methods related to pagination in an attempt to slim down collection.rb
+    module Pagination
+      DEFAULT_PAGE_SIZE = 100
+      def more_results?(response)
+        Helpers.present?(response["meta"]) && response["meta"]["has_more"]
+      end
+      alias has_more_results? more_results? # For backward compatibility with 1.33.0 and 1.34.0
+
+      # Changes the per_page option. Returns self, so it can be chained. No execution.
+      # @return [Collection] self
+      def per_page(count)
+        clear_cache if count
+        @options["per_page"] = count
+        self
+      end
+
+      # Changes the page option. Returns self, so it can be chained. No execution.
+      # @return [Collection] self
+      def page(number)
+        clear_cache if number
+        @options["page"] = number
+        self
+      end
+
+      def first_page?
+        !@prev_page
+      end
+
+      def last_page?
+        !@next_page || @next_page == @query
+      end
+
+      private
+
+      def page_links(body)
+        if body["meta"] && body["links"]
+          [body["links"]["next"], body["links"]["prev"]]
+        else
+          [body["next_page"], body["previous_page"]]
+        end
+      end
+
+      def cbp_response?(body)
+        !!(body["meta"] && body["links"])
+      end
+
+      def set_cbp_options
+        @options_per_page_was = @options.delete("per_page")
+        # Default to CBP by using the page param as a map
+        @options.page = { size: (@options_per_page_was || DEFAULT_PAGE_SIZE) }
+      end
+
+      # CBP requests look like: `/resources?page[size]=100`
+      # OBP requests look like: `/resources?page=2`
+      def cbp_request?
+        @options["page"].is_a?(Hash)
+      end
+
+      def intentional_obp_request?
+        Helpers.present?(@options["page"]) && !cbp_request?
+      end
+
+      def supports_cbp?
+        @resource_class.cbp_path_regexes.any? { |supported_path_regex| path.match?(supported_path_regex) }
+      end
+
+      def first_cbp_request?
+        # @next_page will be nil when making the first cbp request
+        @next_page.nil?
+      end
+
+      def set_page_and_count(body)
+        @count = (body["count"] || @resources.size).to_i
+        @next_page, @prev_page = page_links(body)
+
+        if cbp_response?(body)
+          set_cbp_response_options(body)
+        elsif @next_page =~ /page=(\d+)/
+          @options["page"] = Regexp.last_match(1).to_i - 1
+        elsif @prev_page =~ /page=(\d+)/
+          @options["page"] = Regexp.last_match(1).to_i + 1
+        end
+      end
+
+      def set_cbp_response_options(body)
+        @options.page = {} unless cbp_request?
+        # the line above means an intentional CBP request where page[size] is passed on the query
+        # this is to cater for CBP responses where we don't specify page[size] but the endpoint
+        # responds CBP by default. i.e  `client.trigger_categories.fetch`
+        @options.page.merge!(
+          before: body["meta"]["before_cursor"],
+          after: body["meta"]["after_cursor"]
+                            )
+      end
+    end
+  end
+end

lib/zendesk_api/resource.rb

@@ -163,6 +163,10 @@ def attribute_changes
   class DataResource < Data
     attr_accessor :error, :error_message
     extend Verbs
+
+    def self.cbp_path_regexes
+      []
+    end
   end
 
   # Represents a resource that can only GET