jsonapi-resources 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3cc147ec7ed0dc456d04b86c715a7e9a13f47dd
-  data.tar.gz: 77d151a254fa986e93ba80fd06775ed0bd3753c1
+  metadata.gz: 7639392d6acfd2092e36563bebd32e791b7df37a
+  data.tar.gz: 6c7e794b2646d60214746515810d9648566699e8
 SHA512:
-  metadata.gz: e3349452f04356593d52125551ed57049a91f2b89a66010587d562c12d1fd47ffab5896b8078434bd733a7a931c772478d8615afa30240e66b60b9a9f10ae14f
-  data.tar.gz: 4c75390e027e8af857d049f883836af04e6258ccd57209de458e0d63b809039684febc28720d3a3973e2a65c2068b70775f439b575e33a74b108a7da738bcc9c
+  metadata.gz: 0d53447be085f1ce717782ad9238116e30968e0380fe6e5612e3b5b1a680978285e363904c9c4a96b5ac115bcec8addad959851cd4dfeb58244ab704215eba1c
+  data.tar.gz: 725dd95e1409afd23a1f22a6f7399a8fcc402734adc5da297cc019f65186c2777b3bb8c2aacf7955e1dcd1cc89af1fced6702898222ca2b3746be2e4800bbebc

data/README.md

@@ -330,6 +330,70 @@ class AuthorResource < JSONAPI::Resource
 end
 ```
 
+#### Pagination
+
+Pagination is performed using a `paginator`, which is a class responsible for parsing the `page` request parameters and applying the pagination logic to the results.
+
+##### Paginators
+
+`JSONAPI::Resource` supports several pagination methods by default, and allows you to implement a custom system if the defaults do not meet your needs.
+
+###### Paged Paginator
+
+The `paged` `paginator` returns results based on pages of a fixed size. Valid `page` parameters are `number` and `size`. If `number` is omitted the first page is returned. If `size` is omitted the `default_page_size` from the configuration settings is used.
+
+###### Offset Paginator
+
+The `offset` `paginator` returns results based on an offset from the beginning of the resultset. Valid `page` parameters are `offset` and `limit`. If `offset` is omitted a value of 0 will be used. If `limit` is omitted the `default_page_size` from the configuration settings is used.
+
+###### Custom Paginators
+
+Custom `paginators` can be used. These should derive from `Paginator`. The `apply` method takes a `relation` and is expected to return a `relation`. The `initialize` method receives the parameters from the `page` request parameters. It is up to the paginator author to parse and validate these parameters.
+
+For example, here is a very simple single record at a time paginator:
+
+```ruby
+class SingleRecordPaginator < JSONAPI::Paginator
+  def initialize(params)
+    # param parsing and validation here
+    @page = params.to_i
+  end
+
+  def apply(relation)
+    relation.offset(@page).limit(1)
+  end
+end
+```
+
+##### Paginator Configuration
+
+The default paginator, which will be used for all resources, is set using `JSONAPI.configure`. For example:
+
+```ruby
+JSONAPI.configure do |config|
+  # built in paginators are :none, :offset, :cursor, :paged
+  self.default_paginator = :offset
+
+  self.default_page_size = 10
+  self.maximum_page_size = 20
+end
+```
+
+If no `default_paginator` is configured, pagination will be disabled by default.
+
+Paginators can also be set at the resource-level, which will override the default setting. This is done using the `paginator` method:
+
+```ruby
+class BookResource < JSONAPI::Resource
+  attribute :title
+  attribute :isbn
+
+  paginator :offset
+end
+```
+
+To disable pagination in a resource, specify `:none` for `paginator`.
+
 #### Callbacks
 
 `ActiveSupport::Callbacks` is used to provide callback functionality, so the behavior is very similar to what you may be used to from `ActiveRecord`.
@@ -517,7 +581,10 @@ module JSONAPI
   INVALID_INCLUDE = 112
   RELATION_EXISTS = 113
   INVALID_SORT_PARAM = 114
-
+  INVALID_LINKS_OBJECT = 115
+  TYPE_MISMATCH = 116
+  INVALID_PAGE_OBJECT = 117
+  INVALID_PAGE_VALUE = 118
   RECORD_NOT_FOUND = 404
   LOCKED = 423
 end

data/Rakefile

@@ -1,13 +1,9 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
 require "rake/testtask"
+require './test/test_helper.rb'
 
-desc 'Run tests'
-test_task = Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-end
+TestApp.load_tasks
 
 task default: :test
 
@@ -21,4 +17,4 @@ namespace :test do
       sh cmd.join(' ')
     end
   end
-end
+end

data/lib/jsonapi-resources.rb

@@ -1,6 +1,7 @@
 require 'jsonapi/resource'
 require 'jsonapi/resources/version'
 require 'jsonapi/configuration'
+require 'jsonapi/paginator'
 require 'jsonapi/formatter'
 require 'jsonapi/routing_ext'
 require 'jsonapi/mime_types'

data/lib/jsonapi/configuration.rb

@@ -2,16 +2,29 @@ require 'jsonapi/formatter'
 
 module JSONAPI
   class Configuration
-    attr_reader :json_key_format, :key_formatter, :allowed_request_params, :route_format, :route_formatter
+    attr_reader :json_key_format,
+                :key_formatter,
+                :route_format,
+                :route_formatter,
+                :allowed_request_params,
+                :default_paginator,
+                :default_page_size,
+                :maximum_page_size
 
     def initialize
       #:underscored_key, :camelized_key, :dasherized_key, or custom
-      self.json_key_format = :underscored_key
+      self.json_key_format = :dasherized_key
 
       #:underscored_route, :camelized_route, :dasherized_route, or custom
-      self.route_format = :underscored_route
+      self.route_format = :dasherized_route
 
-      self.allowed_request_params = [:include, :fields, :format, :controller, :action, :sort]
+      self.allowed_request_params = [:include, :fields, :format, :controller, :action, :sort, :page]
+
+      # :none, :offset, :paged, or a custom paginator name
+      self.default_paginator = :none
+
+      self.default_page_size = 10
+      self.maximum_page_size = 20
     end
 
     def json_key_format=(format)
@@ -27,6 +40,18 @@ module JSONAPI
     def allowed_request_params=(allowed_request_params)
       @allowed_request_params = allowed_request_params
     end
+
+    def default_paginator=(default_paginator)
+      @default_paginator = default_paginator
+    end
+
+    def default_page_size=(default_page_size)
+      @default_page_size = default_page_size
+    end
+
+    def maximum_page_size=(maximum_page_size)
+      @maximum_page_size = maximum_page_size
+    end
   end
 
   class << self

data/lib/jsonapi/error_codes.rb

@@ -12,8 +12,12 @@ module JSONAPI
   KEY_NOT_INCLUDED_IN_URL = 110
   INVALID_INCLUDE = 112
   RELATION_EXISTS = 113
-  INVALID_SORT_PARAM = 114
-
+  INVALID_SORT_CRITERIA = 114
+  INVALID_LINKS_OBJECT = 115
+  TYPE_MISMATCH = 116
+  INVALID_PAGE_OBJECT = 117
+  INVALID_PAGE_VALUE = 118
+  INVALID_SORT_FORMAT = 119
   RECORD_NOT_FOUND = 404
   UNSUPPORTED_MEDIA_TYPE = 415
   LOCKED = 423

data/lib/jsonapi/exceptions.rb

@@ -58,18 +58,6 @@ module JSONAPI
       end
     end
 
-    class HasOneRelationExists < Error
-      def initialize
-      end
-
-      def errors
-        [JSONAPI::Error.new(code: JSONAPI::RELATION_EXISTS,
-                            status: :bad_request,
-                            title: 'Relation exists',
-                            detail: 'The relation already exists.')]
-      end
-    end
-
     class FilterNotAllowed < Error
       attr_accessor :filter
       def initialize(filter)
@@ -114,6 +102,34 @@ module JSONAPI
       end
     end
 
+    class InvalidLinksObject < Error
+      attr_accessor :value
+      def initialize(value)
+        @value = value
+      end
+
+      def errors
+        [JSONAPI::Error.new(code: JSONAPI::INVALID_LINKS_OBJECT,
+                            status: :bad_request,
+                            title: 'Invalid Links Object',
+                            detail: "#{value} is not a valid Links Object.")]
+      end
+    end
+
+    class TypeMismatch < Error
+      attr_accessor :type
+      def initialize(type)
+        @type = type
+      end
+
+      def errors
+        [JSONAPI::Error.new(code: JSONAPI::TYPE_MISMATCH,
+                            status: :bad_request,
+                            title: 'Type Mismatch',
+                            detail: "#{type} is not a valid type for this operation.")]
+      end
+    end
+
     class InvalidField < Error
       attr_accessor :field, :type
       def initialize(type, field)
@@ -144,18 +160,33 @@ module JSONAPI
       end
     end
 
-    class InvalidSortParam < Error
-      attr_accessor :sort_param, :resource
-      def initialize(resource, sort_param)
+    class InvalidSortCriteria < Error
+      attr_accessor :sort_criteria, :resource
+      def initialize(resource, sort_criteria)
         @resource = resource
-        @sort_param = sort_param
+        @sort_criteria = sort_criteria
       end
 
       def errors
-        [JSONAPI::Error.new(code: JSONAPI::INVALID_SORT_PARAM,
+        [JSONAPI::Error.new(code: JSONAPI::INVALID_SORT_CRITERIA,
                             status: :bad_request,
-                            title: 'Invalid sort param',
-                            detail: "#{sort_param} is not a valid sort param for #{resource}")]
+                            title: 'Invalid sort criteria',
+                            detail: "#{sort_criteria} is not a valid sort criteria for #{resource}")]
+      end
+    end
+
+    class InvalidSortFormat < Error
+      attr_accessor :sort_criteria, :resource
+      def initialize(resource, sort_criteria)
+        @resource = resource
+        @sort_criteria = sort_criteria
+      end
+
+      def errors
+        [JSONAPI::Error.new(code: JSONAPI::INVALID_SORT_FORMAT,
+                            status: :bad_request,
+                            title: 'Invalid sort format',
+                            detail: "#{sort_criteria} must start with a direction (+ or -)")]
       end
     end
 
@@ -257,5 +288,47 @@ module JSONAPI
       end
     end
 
+    class InvalidPageObject < Error
+      def errors
+        [JSONAPI::Error.new(code: JSONAPI::INVALID_PAGE_OBJECT,
+                            status: :bad_request,
+                            title: 'Invalid Page Object',
+                            detail: 'Invalid Page Object.')]
+      end
+    end
+
+
+    class PageParametersNotAllowed < Error
+      attr_accessor :params
+      def initialize(params)
+        @params = params
+      end
+
+      def errors
+        params.collect { |param|
+          JSONAPI::Error.new(code: JSONAPI::PARAM_NOT_ALLOWED,
+                             status: :bad_request,
+                             title: 'Page parameter not allowed',
+                             detail: "#{param} is not an allowed page parameter.")
+        }
+
+      end
+    end
+
+    class InvalidPageValue < Error
+      attr_accessor :page, :value
+      def initialize(page, value, msg = nil)
+        @page = page
+        @value = value
+        @msg = msg.nil? ? "#{value} is not a valid value for #{page} page parameter." : msg
+      end
+
+      def errors
+        [JSONAPI::Error.new(code: JSONAPI::INVALID_PAGE_VALUE,
+                            status: :bad_request,
+                            title: 'Invalid page value',
+                            detail: @msg)]
+      end
+    end
   end
 end

data/lib/jsonapi/operation.rb

@@ -68,24 +68,6 @@ module JSONAPI
     end
   end
 
-  class CreateHasOneAssociationOperation < Operation
-    attr_reader :resource_id, :association_type, :key_value
-
-    def initialize(resource_klass, resource_id, association_type, key_value)
-      @resource_id = resource_id
-      @key_value = key_value
-      @association_type = association_type.to_sym
-      super(resource_klass)
-    end
-
-    def apply(context)
-      resource = @resource_klass.find_by_key(@resource_id, context: context)
-      resource.create_has_one_link(@association_type, @key_value)
-
-      return JSONAPI::OperationResult.new(:no_content)
-    end
-  end
-
   class ReplaceHasOneAssociationOperation < Operation
     attr_reader :resource_id, :association_type, :key_value
 

data/lib/jsonapi/paginator.rb

@@ -0,0 +1,98 @@
+module JSONAPI
+  class Paginator
+    def initialize(params)
+    end
+
+    def apply(relation)
+      # :nocov:
+      relation
+      # :nocov:
+    end
+
+    class << self
+      # :nocov:
+      if RUBY_VERSION >= '2.0'
+        def paginator_for(paginator)
+          paginator_class_name = "#{paginator.to_s.camelize}Paginator"
+          Object.const_get(paginator_class_name) if paginator_class_name
+        end
+      else
+        def paginator_for(paginator)
+          paginator_class_name = "#{paginator.to_s.camelize}Paginator"
+          paginator_class_name.safe_constantize if paginator_class_name
+        end
+      end
+      # :nocov:
+    end
+  end
+end
+
+class OffsetPaginator < JSONAPI::Paginator
+  def initialize(params)
+    parse_pagination_params(params)
+  end
+
+  def apply(relation)
+    relation.offset(@offset).limit(@limit)
+  end
+
+  private
+  def parse_pagination_params(params)
+    if params.nil?
+      @offset = 0
+      @limit = JSONAPI.configuration.default_page_size
+    elsif params.is_a?(ActionController::Parameters)
+      validparams = params.permit(:offset, :limit)
+
+      @offset = validparams[:offset] ? validparams[:offset].to_i : 0
+      @limit = validparams[:limit] ? validparams[:limit].to_i : JSONAPI.configuration.default_page_size
+
+      if @limit < 1
+        raise JSONAPI::Exceptions::InvalidPageValue.new(:limit, validparams[:limit])
+      elsif @limit > JSONAPI.configuration.maximum_page_size
+        raise JSONAPI::Exceptions::InvalidPageValue.new(:limit, validparams[:limit],
+                                                        "Limit exceeds maximum page size of #{JSONAPI.configuration.maximum_page_size}.")
+      end
+    else
+      raise JSONAPI::Exceptions::InvalidPageObject.new
+    end
+  rescue ActionController::UnpermittedParameters => e
+    raise JSONAPI::Exceptions::PageParametersNotAllowed.new(e.params)
+  end
+end
+
+class PagedPaginator < JSONAPI::Paginator
+  def initialize(params)
+    parse_pagination_params(params)
+  end
+
+  def apply(relation)
+    offset = (@number - 1) * @size
+    relation.offset(offset).limit(@size)
+  end
+
+  private
+  def parse_pagination_params(params)
+    if params.nil?
+      @number = 1
+      @size = JSONAPI.configuration.default_page_size
+    elsif params.is_a?(ActionController::Parameters)
+      validparams = params.permit(:number, :size)
+
+      @size = validparams[:size] ? validparams[:size].to_i : JSONAPI.configuration.default_page_size
+      @number = validparams[:number] ? validparams[:number].to_i : 1
+
+      if @size < 1
+        raise JSONAPI::Exceptions::InvalidPageValue.new(:size, validparams[:size])
+      elsif @size > JSONAPI.configuration.maximum_page_size
+        raise JSONAPI::Exceptions::InvalidPageValue.new(:size, validparams[:size],
+                                                        "size exceeds maximum page size of #{JSONAPI.configuration.maximum_page_size}.")
+      end
+    else
+      @size = JSONAPI.configuration.default_page_size
+      @number = params.to_i
+    end
+  rescue ActionController::UnpermittedParameters => e
+    raise JSONAPI::Exceptions::PageParametersNotAllowed.new(e.params)
+  end
+end