Merge pull request #83 from cerebris/jsonapi_rc2

Jsonapi rc2

Author: dgeb

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

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

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'

lib/jsonapi/configuration.rb

@@ -2,16 +2,29 @@
 
 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 @@ def route_format=(format)
     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

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

lib/jsonapi/exceptions.rb

@@ -58,18 +58,6 @@ def errors
       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 @@ def errors
       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 @@ def errors
       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 @@ def errors
       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

lib/jsonapi/operation.rb

@@ -68,24 +68,6 @@ def apply(context)
     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