jsonapi-resources 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1c7d37d8e26cb718f177ebe4fd12161d43196be
-  data.tar.gz: 944229a81d8e325bfd3fae18f39f97fb4716a346
+  metadata.gz: f3abcdf22a7970e7b4e51d624771006f875e857f
+  data.tar.gz: 26703852c97b53b7a044f545a16256024d67522a
 SHA512:
-  metadata.gz: 750930c916c0ed48ae7fc0f1dd9b19f4d3a853f1fefd27440df9736559650e21ddec7009e94ffcccc2de6133b7b8ae0e89fa2c7f0e96587562311b50c561d3fb
-  data.tar.gz: 1aa6132ee9712c7bdd6636090be1be3c243a823140376d6b21ede7026a77cc9c4b8a7eba6dff68b543f589650ae997f4fb13d1f360e27af3a23c45b1d5cc3bcb
+  metadata.gz: fa580d57a12f10e6bd3732ab0b4c6b3818b8daa81ce995110f810d05e71ef16ed4f56b934ccd518c731aca4d617621070fa61e86363acd7fdd72167ffd58fa8e
+  data.tar.gz: 96acb9c3f10654468c1639cd867e0658dc575318b3a452e463955ead6a64f885dbd5482a3b8a4dd803ae76b684560d839c67f507bd925b465f8f90811a43da41

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
+sudo: false
 env:
   - "RAILS_VERSION=4.0"
   - "RAILS_VERSION=4.1"

data/README.md

@@ -1,4 +1,4 @@
-# JSONAPI::Resources [![Build Status](https://secure.travis-ci.org/cerebris/jsonapi-resources.png?branch=master)](http://travis-ci.org/cerebris/jsonapi-resources)
+# JSONAPI::Resources [![Build Status](https://secure.travis-ci.org/cerebris/jsonapi-resources.png?branch=master)](http://travis-ci.org/cerebris/jsonapi-resources) [![Code Climate](https://codeclimate.com/github/cerebris/jsonapi-resources/badges/gpa.svg)](https://codeclimate.com/github/cerebris/jsonapi-resources)
 
 `JSONAPI::Resources`, or "JR", provides a framework for developing a server that complies with the
 [JSON API](http://jsonapi.org/) specification.
@@ -178,10 +178,10 @@ updating the attribute. See the [Value Formatters](#value-formatters) section fo
 
 #### Primary Key
 
-Resources are always represented using a key of `id`. If the underlying model does not use `id` as the primary key you
-can use the `primary_key` method to tell the resource which field on the model to use as the primary key. Note: this
-doesn't have to be the actual primary key of the model. For example you may wish to use integers internally and a
-different scheme publicly.
+Resources are always represented using a key of `id`. The resource will interrogate the model to find the primary key.
+If the underlying model does not use `id` as the primary key _and_ does not support the `primary_key` method you
+must use the `primary_key` method to tell the resource which field on the model to use as the primary key. **Note:**
+this _must_ be the actual primary key of the model.
 
 By default only integer values are allowed for primary key. To change this behavior you can override
 `verify_key` class method:
@@ -212,11 +212,33 @@ class AuthorResource < JSONAPI::Resource
 end
 ```
 
-#### Associations
+#### Relationships
 
-Related resources need to be specified in the resource. These are declared with the `has_one` and the `has_many` methods.
+Related resources need to be specified in the resource. These may be declared with the `relationship` or the `has_one`
+and the `has_many` methods.
 
-Here's a simple example where a post has a single author and an author can have many posts:
+Here's a simple example using the `relationship` method where a post has a single author and an author can have many
+posts:
+
+```ruby
+class PostResource < JSONAPI::Resource
+  attribute :title, :body
+
+  relationship :author, to: :one
+end
+```
+
+And the corresponding author:
+
+```ruby
+class AuthorResource < JSONAPI::Resource
+  attribute :name
+
+  relationship :posts, to: :many
+end
+```
+
+And here's the equivalent resources using the `has_one` and `has_many` methods:
 
 ```ruby
 class PostResource < JSONAPI::Resource
@@ -238,14 +260,17 @@ end
 
 ##### Options
 
-The association methods support the following options:
+The relationship methods (`relationship`, `has_one`, and `has_many`) support the following options:
 
  * `class_name` - a string specifying the underlying class for the related resource
  * `foreign_key` - the method on the resource used to fetch the related resource. Defaults to `<resource_name>_id` for has_one and `<resource_name>_ids` for has_many relationships.
  * `acts_as_set` - allows the entire set of related records to be replaced in one operation. Defaults to false if not set.
- * `polymorphic` - set to true to identify associations that are polymorphic.
+ * `polymorphic` - set to true to identify relationships that are polymorphic.
  * `relation_name` - the name of the relation to use on the model. A lambda may be provided which allows conditional selection of the relation based on the context.
 
+`to_one` relationships support the additional option:
+ * `foreign_key_on` - defaults to `:self`. To indicate that the foreign key is on the related resource specify `:related`.
+ 
 Examples:
 
 ```ruby
@@ -286,8 +311,10 @@ class BookResource < JSONAPI::Resource
   }
   ...
 end
+```
 
-The polymorphic association will require the resource and controller to exist, although routing to them will cause an error.
+The polymorphic relationship will require the resource and controller to exist, although routing to them will cause an
+error.
 
 ```ruby
 class TaggableResource < JSONAPI::Resource; end
@@ -297,7 +324,8 @@ class TaggablesController < JSONAPI::ResourceController; end
 #### Filters
 
 Filters for locating objects of the resource type are specified in the resource definition. Single filters can be
-declared using the `filter` method, and multiple filters can be declared with the `filters` method on the resource class.
+declared using the `filter` method, and multiple filters can be declared with the `filters` method on the resource
+class.
 
 For example:
 
@@ -310,7 +338,8 @@ class ContactResource < JSONAPI::Resource
 end
 ```
 
-Then a request could pass in a filter for example `http://example.com/contacts?filter[name_last]=Smith` and the system will find all people where the last name exactly matches Smith.
+Then a request could pass in a filter for example `http://example.com/contacts?filter[name_last]=Smith` and the system 
+will find all people where the last name exactly matches Smith.
 
 ##### Default Filters
 
@@ -356,7 +385,7 @@ end
 ```
 
 When you create a relationship, a method is created to fetch record(s) for that relationship. This method calls
-`records_for(association_name)` by default.
+`records_for(relationship_name)` by default.
 
 ```ruby
 class PostResource < JSONAPI::Resource
@@ -374,13 +403,13 @@ end
 
 ```
 
-For example, you may want raise an error if the user is not authorized to view the associated records.
+For example, you may want raise an error if the user is not authorized to view the related records.
 
 ```ruby
 class BaseResource < JSONAPI::Resource
-  def records_for(association_name, options={})
+  def records_for(relationship_name, options={})
     context = options[:context]
-    records = model.public_send(association_name)
+    records = model.public_send(relationship_name)
 
     unless context.current_user.can_view?(records)
       raise NotAuthorizedError
@@ -563,17 +592,17 @@ Callbacks can also be defined for `JSONAPI::OperationsProcessor` events:
 - `:operation`: Any individual operation.
 - `:find_operation`: A `find_operation`.
 - `:show_operation`: A `show_operation`.
-- `:show_association_operation`: A `show_association_operation`.
+- `:show_relationship_operation`: A `show_relationship_operation`.
 - `:show_related_resource_operation`: A `show_related_resource_operation`.
 - `:show_related_resources_operation`: A `show_related_resources_operation`.
 - `:create_resource_operation`: A `create_resource_operation`.
 - `:remove_resource_operation`: A `remove_resource_operation`.
 - `:replace_fields_operation`: A `replace_fields_operation`.
-- `:replace_has_one_association_operation`: A `replace_has_one_association_operation`.
-- `:create_has_many_association_operation`: A `create_has_many_association_operation`.
-- `:replace_has_many_association_operation`: A `replace_has_many_association_operation`.
-- `:remove_has_many_association_operation`: A `remove_has_many_association_operation`.
-- `:remove_has_one_association_operation`: A `remove_has_one_association_operation`.
+- `:replace_has_one_relationship_operation`: A `replace_has_one_relationship_operation`.
+- `:create_has_many_relationship_operation`: A `create_has_many_relationship_operation`.
+- `:replace_has_many_relationship_operation`: A `replace_has_many_relationship_operation`.
+- `:remove_has_many_relationship_operation`: A `remove_has_many_relationship_operation`.
+- `:remove_has_one_relationship_operation`: A `remove_has_one_relationship_operation`.
 
 The operation callbacks have access to two meta data hashes, `@operations_meta` and `@operation_meta`, two links hashes,
 `@operations_links` and `@operation_links`, the full list of `@operations`, each individual `@operation` and the
@@ -874,7 +903,7 @@ An array of resources. Nested resources can be specified with dot notation.
 A hash of resource types and arrays of fields for each resource type.
 
   *Purpose*: determines which fields are serialized for a resource type. This encompasses both attributes and
-  association ids in the links section for a resource. Fields are global for a resource type.
+  relationship ids in the links section for a resource. Fields are global for a resource type.
 
   *Example*: ```fields: { people: [:email, :comments], posts: [:title, :author], comments: [:body, :post]}```
 
@@ -903,7 +932,7 @@ JR has a couple of helper methods available to assist you with setting up routes
 ##### `jsonapi_resources`
 
 Like `resources` in `ActionDispatch`, `jsonapi_resources` provides resourceful routes mapping between HTTP verbs and URLs
-and controller actions. This will also setup mappings for relationship URLs for a resource's associations. For example:
+and controller actions. This will also setup mappings for relationship URLs for a resource's relationships. For example:
 
 ```ruby
 Rails.application.routes.draw do
@@ -916,20 +945,20 @@ gives the following routes
 
 ```
                      Prefix Verb      URI Pattern                                               Controller#Action
-contact_links_phone_numbers GET       /contacts/:contact_id/links/phone-numbers(.:format)       contacts#show_association {:association=>"phone_numbers"}
-                            POST      /contacts/:contact_id/links/phone-numbers(.:format)       contacts#create_association {:association=>"phone_numbers"}
-                            DELETE    /contacts/:contact_id/links/phone-numbers/:keys(.:format) contacts#destroy_association {:association=>"phone_numbers"}
-      contact_phone_numbers GET       /contacts/:contact_id/phone-numbers(.:format)             phone_numbers#get_related_resources {:association=>"phone_numbers", :source=>"contacts"}
+contact_relationships_phone_numbers GET       /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#show_relationship {:relationship=>"phone_numbers"}
+                            POST      /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#create_relationship {:relationship=>"phone_numbers"}
+                            DELETE    /contacts/:contact_id/relationships/phone-numbers/:keys(.:format) contacts#destroy_relationship {:relationship=>"phone_numbers"}
+      contact_phone_numbers GET       /contacts/:contact_id/phone-numbers(.:format)             phone_numbers#get_related_resources {:relationship=>"phone_numbers", :source=>"contacts"}
                    contacts GET       /contacts(.:format)                                       contacts#index
                             POST      /contacts(.:format)                                       contacts#create
                     contact GET       /contacts/:id(.:format)                                   contacts#show
                             PATCH     /contacts/:id(.:format)                                   contacts#update
                             PUT       /contacts/:id(.:format)                                   contacts#update
                             DELETE    /contacts/:id(.:format)                                   contacts#destroy
- phone_number_links_contact GET       /phone-numbers/:phone_number_id/links/contact(.:format)   phone_numbers#show_association {:association=>"contact"}
-                            PUT|PATCH /phone-numbers/:phone_number_id/links/contact(.:format)   phone_numbers#update_association {:association=>"contact"}
-                            DELETE    /phone-numbers/:phone_number_id/links/contact(.:format)   phone_numbers#destroy_association {:association=>"contact"}
-       phone_number_contact GET       /phone-numbers/:phone_number_id/contact(.:format)         contacts#get_related_resource {:association=>"contact", :source=>"phone_numbers"}
+ phone_number_relationships_contact GET       /phone-numbers/:phone_number_id/relationships/contact(.:format)   phone_numbers#show_relationship {:relationship=>"contact"}
+                            PUT|PATCH /phone-numbers/:phone_number_id/relationships/contact(.:format)   phone_numbers#update_relationship {:relationship=>"contact"}
+                            DELETE    /phone-numbers/:phone_number_id/relationships/contact(.:format)   phone_numbers#destroy_relationship {:relationship=>"contact"}
+       phone_number_contact GET       /phone-numbers/:phone_number_id/contact(.:format)         contacts#get_related_resource {:relationship=>"contact", :source=>"phone_numbers"}
               phone_numbers GET       /phone-numbers(.:format)                                  phone_numbers#index
                             POST      /phone-numbers(.:format)                                  phone_numbers#create
                phone_number GET       /phone-numbers/:id(.:format)                              phone_numbers#show
@@ -994,9 +1023,9 @@ end
 Gives the following routes:
 
 ```
-contact_links_phone_numbers GET    /contacts/:contact_id/links/phone-numbers(.:format)       contacts#show_association {:association=>"phone_numbers"}
-                            POST   /contacts/:contact_id/links/phone-numbers(.:format)       contacts#create_association {:association=>"phone_numbers"}
-                            DELETE /contacts/:contact_id/links/phone-numbers/:keys(.:format) contacts#destroy_association {:association=>"phone_numbers"}
+contact_relationships_phone_numbers GET    /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#show_relationship {:relationship=>"phone_numbers"}
+                            POST   /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#create_relationship {:relationship=>"phone_numbers"}
+                            DELETE /contacts/:contact_id/relationships/phone-numbers/:keys(.:format) contacts#destroy_relationship {:relationship=>"phone_numbers"}
                    contacts GET    /contacts(.:format)                                       contacts#index
                             POST   /contacts(.:format)                                       contacts#create
                     contact GET    /contacts/:id(.:format)                                   contacts#show
@@ -1006,7 +1035,7 @@ contact_links_phone_numbers GET    /contacts/:contact_id/links/phone-numbers(.:f
 
 ```
 
-The new routes allow you to show, create and destroy the associations between resources.
+The new routes allow you to show, create and destroy the relationships between resources.
 
 ###### `jsonapi_related_resources`
 
@@ -1025,7 +1054,7 @@ gives the following routes:
 
 ```
                Prefix Verb   URI Pattern                                   Controller#Action
-contact_phone_numbers GET    /contacts/:contact_id/phone-numbers(.:format) phone_numbers#get_related_resources {:association=>"phone_numbers", :source=>"contacts"}
+contact_phone_numbers GET    /contacts/:contact_id/phone-numbers(.:format) phone_numbers#get_related_resources {:relationship=>"phone_numbers", :source=>"contacts"}
              contacts GET    /contacts(.:format)                           contacts#index
                       POST   /contacts(.:format)                           contacts#create
               contact GET    /contacts/:id(.:format)                       contacts#show
@@ -1053,7 +1082,7 @@ gives the following routes:
 
 ```
               Prefix Verb   URI Pattern                                       Controller#Action
-phone_number_contact GET    /phone-numbers/:phone_number_id/contact(.:format) contacts#get_related_resource {:association=>"contact", :source=>"phone_numbers"}
+phone_number_contact GET    /phone-numbers/:phone_number_id/contact(.:format) contacts#get_related_resource {:relationship=>"contact", :source=>"phone_numbers"}
        phone_numbers GET    /phone-numbers(.:format)                          phone_numbers#index
                      POST   /phone-numbers(.:format)                          phone_numbers#create
         phone_number GET    /phone-numbers/:id(.:format)                      phone_numbers#show
@@ -1248,6 +1277,11 @@ JSONAPI.configure do |config|
   # catch this error and render a 403 status code, you should add
   # the `Pundit::NotAuthorizedError` to the `exception_class_whitelist`.
   config.exception_class_whitelist = []
+  
+  # Resource Linkage
+  # Controls the serialization of resource linkage for non compound documents
+  # NOTE: always_include_has_many_linkage_data is not currently implemented
+  config.always_include_has_one_linkage_data = false  
 end
 ```
 

data/lib/jsonapi-resources.rb

@@ -15,8 +15,9 @@ require 'jsonapi/error_codes'
 require 'jsonapi/request'
 require 'jsonapi/operations_processor'
 require 'jsonapi/active_record_operations_processor'
-require 'jsonapi/association'
+require 'jsonapi/relationship'
 require 'jsonapi/include_directives'
 require 'jsonapi/operation_result'
 require 'jsonapi/operation_results'
 require 'jsonapi/callbacks'
+require 'jsonapi/link_builder'

data/lib/jsonapi/acts_as_resource_controller.rb

@@ -5,7 +5,7 @@ module JSONAPI
     extend ActiveSupport::Concern
 
     included do
-      before_filter :ensure_correct_media_type, only: [:create, :update, :create_association, :update_association]
+      before_filter :ensure_correct_media_type, only: [:create, :update, :create_relationship, :update_relationship]
       append_before_filter :setup_request
       after_filter :setup_response
     end
@@ -18,7 +18,7 @@ module JSONAPI
       process_request_operations
     end
 
-    def show_association
+    def show_relationship
       process_request_operations
     end
 
@@ -26,11 +26,11 @@ module JSONAPI
       process_request_operations
     end
 
-    def create_association
+    def create_relationship
       process_request_operations
     end
 
-    def update_association
+    def update_relationship
       process_request_operations
     end
 
@@ -42,7 +42,7 @@ module JSONAPI
       process_request_operations
     end
 
-    def destroy_association
+    def destroy_relationship
       process_request_operations
     end
 

data/lib/jsonapi/configuration.rb

@@ -17,7 +17,9 @@ module JSONAPI
                 :top_level_links_include_pagination,
                 :top_level_meta_include_record_count,
                 :top_level_meta_record_count_key,
-                :exception_class_whitelist
+                :exception_class_whitelist,
+                :always_include_to_one_linkage_data,
+                :always_include_to_many_linkage_data
 
     def initialize
       #:underscored_key, :camelized_key, :dasherized_key, or custom
@@ -54,6 +56,12 @@ module JSONAPI
       # catch this error and render a 403 status code, you should add
       # the `Pundit::NotAuthorizedError` to the `exception_class_whitelist`.
       self.exception_class_whitelist = []
+
+      # Resource Linkage
+      # Controls the serialization of resource linkage for non compound documents
+      # NOTE: always_include_to_many_linkage_data is not currently implemented
+      self.always_include_to_one_linkage_data = false
+      self.always_include_to_many_linkage_data = false
     end
 
     def json_key_format=(format)
@@ -88,6 +96,10 @@ module JSONAPI
     attr_writer :top_level_meta_record_count_key
 
     attr_writer :exception_class_whitelist
+
+    attr_writer :always_include_to_one_linkage_data
+
+    attr_writer :always_include_to_many_linkage_data
   end
 
   class << self

data/lib/jsonapi/error.rb

@@ -1,6 +1,6 @@
 module JSONAPI
   class Error
-    attr_accessor :title, :detail, :id, :href, :code, :path, :links, :status
+    attr_accessor :title, :detail, :id, :href, :code, :source, :links, :status
 
     def initialize(options = {})
       @title          = options[:title]
@@ -12,7 +12,7 @@ module JSONAPI
                         else
                           options[:code]
                         end
-      @path           = options[:path]
+      @source         = options[:source]
       @links          = options[:links]
       @status         = options[:status]
     end

data/lib/jsonapi/exceptions.rb

@@ -73,12 +73,12 @@ module JSONAPI
       end
     end
 
-    class HasManySetReplacementForbidden < Error
+    class ToManySetReplacementForbidden < Error
       def errors
         [JSONAPI::Error.new(code: JSONAPI::FORBIDDEN,
                             status: :forbidden,
                             title: 'Complete replacement forbidden',
-                            detail: 'Complete replacement forbidden for this association')]
+                            detail: 'Complete replacement forbidden for this relationship')]
       end
     end
 
@@ -188,17 +188,17 @@ module JSONAPI
     end
 
     class InvalidInclude < Error
-      attr_accessor :association, :resource
-      def initialize(resource, association)
+      attr_accessor :relationship, :resource
+      def initialize(resource, relationship)
         @resource = resource
-        @association = association
+        @relationship = relationship
       end
 
       def errors
         [JSONAPI::Error.new(code: JSONAPI::INVALID_INCLUDE,
                             status: :bad_request,
                             title: 'Invalid field',
-                            detail: "#{association} is not a valid association of #{resource}")]
+                            detail: "#{relationship} is not a valid relationship of #{resource}")]
       end
     end
 
@@ -294,9 +294,11 @@ module JSONAPI
     end
 
     class ValidationErrors < Error
-      attr_accessor :messages
-      def initialize(messages)
-        @messages = messages
+      attr_reader :error_messages, :resource_relationships
+
+      def initialize(resource)
+        @error_messages = resource.model.errors.messages
+        @resource_relationships = resource.class._relationships.keys
         @key_formatter = JSONAPI.configuration.key_formatter
       end
 
@@ -305,16 +307,26 @@ module JSONAPI
       end
 
       def errors
-        messages.inject([]) do |arr, element|
-          arr.concat(
-            element[1].map do |message|
-              JSONAPI::Error.new(code: JSONAPI::VALIDATION_ERROR,
-                                 status: :unprocessable_entity,
-                                 title: "#{format_key(element[0])} - #{message}",
-                                 detail: message,
-                                 path: "/#{element[0]}")
-            end
-          )
+        error_messages.flat_map do |attr_key, messages|
+          messages.map { |message| json_api_error(attr_key, message) }
+        end
+      end
+
+      private
+
+      def json_api_error(attr_key, message)
+        JSONAPI::Error.new(code: JSONAPI::VALIDATION_ERROR,
+                           status: :unprocessable_entity,
+                           title: "#{format_key(attr_key)} - #{message}",
+                           detail: message,
+                           source: { pointer: pointer(attr_key) })
+      end
+
+      def pointer(attr_or_relationship_name)
+        if resource_relationships.include?(attr_or_relationship_name)
+          "/data/relationships/#{attr_or_relationship_name}"
+        else
+          "/data/attributes/#{attr_or_relationship_name}"
         end
       end
     end
@@ -358,7 +370,7 @@ module JSONAPI
       def initialize(page, value, msg = nil)
         @page = page
         @value = value
-        @msg = msg.nil? ? "#{value} is not a valid value for #{page} page parameter." : msg
+        @msg = msg || "#{value} is not a valid value for #{page} page parameter."
       end
 
       def errors