Add support for returning pagination info

README.md

@@ -35,18 +35,22 @@ Basic usage of a `Ioki::Client`
   products = platform_client.products
   # returns a list of Ioki::Model::Platform::Product instances
 
-  stations = platform_client.stations(products.first, auto_paginate: true)
-  # stations are a scoped endpoint within products, to the interface requires
+  stations = platform_client.stations(products.first, paginate: true)
+  # stations are a scoped endpoint within products, so the interface requires
   # either a product or a product id as the first parameter.
-  # This call will then fetch the index of stations. This example also shows
-  # auto_pagination, which keeps calling the index until the last page was
-  # fetched. Bear in mind, that auto_pagination might be extremely expensive.
+  # This call will then fetch the index of stations. Use `paginate: true` to
+  # receive pagination information in the response. Otherwise, only the data of
+  # the first page is returned.
+  unless stations.meta.last_page
+    next_page = stations.meta.page + 1
+    stations = platform_client.stations(products.first, params: {page: next_page}, paginate: true)
+  end
 
   new_station = Ioki::Model::Platform::Station.new(
     location_name: 'Test',
     station_type: 'virtual',
-    lat: stations.first.lat,
-    lng: stations.first.lng
+    lat: stations.data.first.lat,
+    lng: stations.data.first.lng
   )
 
   created_station = platform_client.create_station(products.first, new_station)
@@ -57,6 +61,12 @@ Basic usage of a `Ioki::Client`
 
   platform_client.delete_station(products.first, created_station)
   # will delete the formerly created station
+
+  stations = platform_client.stations(products.first, auto_paginate: true)
+  # This example shows auto_pagination, which keeps calling the index until the
+  # last page was fetched. Bear in mind, that auto_pagination might be extremely
+  # expensive.
+  first_station = stations.first
 ```
 
 See `spec/ioki/examples` for more examples.

lib/ioki/apis/endpoints/index.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../model/response'
+
 module Endpoints
   class Index
     attr_reader :model_class, :base_path, :resource, :path
@@ -24,9 +26,15 @@ def full_path
     end
 
     def call(client, args = [], options = {}, &block)
+      options = options.dup
+      paginate = options.delete(:paginate)
       auto_paginate = options.delete(:auto_paginate)
 
-      if auto_paginate
+      if paginate
+        data, parsed_response = send_request(client, args, options)
+
+        Ioki::Model::Response.new(data, parsed_response.dig('meta'))
+      elsif auto_paginate
         paginated_requests(client, args, options, &block)
       elsif block_given?
         send_request(client, args, options).first.each { |item| block.call(item) }

lib/ioki/model/meta.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Ioki
+  module Model
+    class Meta
+      attr_reader :page, :last_page
+
+      def initialize(attributes)
+        @page = attributes['page']
+        @last_page = attributes['last_page']
+      end
+    end
+  end
+end

lib/ioki/model/response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'meta'
+
+module Ioki
+  module Model
+    class Response
+      attr_reader :data, :meta
+
+      def initialize(data, meta)
+        @data = data
+        @meta = Ioki::Model::Meta.new(meta)
+      end
+    end
+  end
+end