jsonapi-resources 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d4cbc3730824bb1f4ad419724a0a472fd16d2e0
-  data.tar.gz: 7b30da4000a4c8996bd2e2eb2cc8288e9303b728
+  metadata.gz: 51cd49198136e8a49dd3bb8138721babc499c0cf
+  data.tar.gz: 29ddb62840cb17c2e753cfb03ab5e5cfe9dcdbe0
 SHA512:
-  metadata.gz: 00aa2506b52f8635e7f7c92ef5755bf2028c4229bdc55aef4dca8339151af3222f05f677b4b2d26af91e55ec3d04ce9bc765d4e2552691662936634cfed69bd1
-  data.tar.gz: 75e1b2f23fc2b9f8f046768cb213edd888b951ae3a490c2d5890381141674283ab8fe26c701cce6948e43e3c15978127eb1b9d9039e129d03c6cb79e7123500c
+  metadata.gz: 276688390c5ae3d33ab1c40ea8a181ed8024c8c99cca514de6a941f52a64ace4b39b81b4aaba7222730b5d0604ec9e52a6cb48e0a49d61933df148daf0ecba3f
+  data.tar.gz: bd36f549771a05afb8efec6ef4337e3888a9b2d9ad153fd870cba852c06c353a32b42484e0eb9b84cbfbfa5c3a14dfcb3254b0d1c3c07099f0debe849524a583

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.1

data/README.md

@@ -1,4 +1,4 @@
-# JSONAPI::Resources
+# JSONAPI::Resources [![Build Status](https://secure.travis-ci.org/cerebris/jsonapi-resources.png?branch=master)](http://travis-ci.org/cerebris/jsonapi-resources)
 
 JSONAPI::Resources, or "JR", provides a framework for developing a server that complies with the [JSON API](http://jsonapi.org/) specification.
 
@@ -8,7 +8,7 @@ JR is designed to work with Rails, and provides custom routes, controllers, and
 
 ## Demo App
 
-We have a simple demo app, called [Peeps](https://github.com/cerebris/peeps), available to show how JR is used. 
+We have a simple demo app, called [Peeps](https://github.com/cerebris/peeps), available to show how JR is used.
 
 ## Installation
 
@@ -38,7 +38,7 @@ Resources must be derived from `JSONAPI::Resource`, or a class that is itself de
 
 For example:
 
-```
+```ruby
 require 'jsonapi/resource'
 
 class ContactResource < JSONAPI::Resource
@@ -51,7 +51,7 @@ Any of a resource's attributes that are accessible must be explicitly declared.
 
 For example:
 
-```
+```ruby
 require 'jsonapi/resource'
 
 class ContactResource < JSONAPI::Resource
@@ -63,11 +63,11 @@ end
 
 This resource has 5 attributes: `:id`, `:name_first`, `:name_last`, `:email`, `:twitter`. By default these attributes must exist on the model that is handled by the resource.
 
-A resource object wraps a Ruby object, usually an ActiveModel record, which is available as the `@object` variable. This allows a resource's methods to access the underlying object. 
+A resource object wraps a Ruby object, usually an ActiveModel record, which is available as the `@object` variable. This allows a resource's methods to access the underlying object.
 
 For example, a computed attribute for `full_name` could be defined as such:
 
-```
+```ruby
 require 'jsonapi/resource'
 
 class ContactResource < JSONAPI::Resource
@@ -82,11 +82,11 @@ end
 
 ##### Fetchable Attributes
 
-By default all attributes are assumed to be fetchable. The list of fetchable attributes can be filtered by overriding the `fetchable` method. 
+By default all attributes are assumed to be fetchable. The list of fetchable attributes can be filtered by overriding the `fetchable` method.
 
 Here's an example that prevents guest users from seeing the `email` field:
 
-```
+```ruby
 class AuthorResource < JSONAPI::Resource
   attributes :id, :name, :email
   model_name 'Person'
@@ -110,7 +110,7 @@ By default all attributes are assumed to be updateble and creatable. To prevent
 
 This example prevents `full_name` from being set:
 
-```
+```ruby
 require 'jsonapi/resource'
 
 class ContactResource < JSONAPI::Resource
@@ -119,7 +119,7 @@ class ContactResource < JSONAPI::Resource
   def full_name
     "#{@object.name_first}, #{@object.name_last}"
   end
-  
+
   def self.updateable(keys, context = nil)
     super(keys - [:full_name])
   end
@@ -132,11 +132,24 @@ end
 
 The `context` is not used by the `ResourceController`, but may be used if you override the controller methods.
 
+##### Attribute Formatting
+
+Attributes can have a Format. By default all attributes use the default formatter. If an attribute has the `format` option set the system will attempt to find a formatter based on this name. In the following example the `last_login_time` will be returned formatted to a certain time zone:
+
+```
+class PersonResource < JSONAPI::Resource
+  attributes :id, :name, :email
+  attribute :last_login_time, format: :date_with_timezone
+end
+```
+
+The system will lookup a value formatter named `DateWithTimezoneValueFormatter` and will use this when serializing and updating the attribute. See the [Value Formatters](#value-formatters) section for more details.
+
 #### Key
 
 The primary key of the resource defaults to `id`, which can be changed using the `key` method.
 
-```
+```ruby
 class CurrencyResource < JSONAPI::Resource
   key :code
   attributes :code, :name
@@ -150,7 +163,7 @@ end
 
 The name of the underlying model is inferred from the Resource name. It can be overridden by use of the `model_name` method. For example:
 
-```
+```ruby
 class AuthorResource < JSONAPI::Resource
   attributes :id, :name
   model_name 'Person'
@@ -160,11 +173,11 @@ end
 
 #### Associations
 
-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 are declared with 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:
 
-```
+```ruby
 class PostResource < JSONAPI::Resource
   attribute :id, :title, :body
 
@@ -174,7 +187,7 @@ end
 
 And the corresponding author:
 
-```
+```ruby
 class AuthorResource < JSONAPI::Resource
   attribute :id, :name
 
@@ -192,7 +205,7 @@ The association methods support the following options:
 
 Examples:
 
-```
+```ruby
  class CommentResource < JSONAPI::Resource
   attributes :id, :body
   has_one :post
@@ -201,7 +214,7 @@ Examples:
  end
 ```
 
-```
+```ruby
 class ExpenseEntryResource < JSONAPI::Resource
   attributes :id, :cost, :transaction_date
 
@@ -213,11 +226,11 @@ 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. 
+resource class.
 
 For example:
 
-```
+```ruby
 require 'jsonapi/resource'
 
 class ContactResource < JSONAPI::Resource
@@ -234,7 +247,7 @@ Basic finding by filters is supported by resources. However if you have more com
 
 Here's an example that defers the `find` operation to a `current_user` set on the `context`:
 
-```
+```ruby
 class AuthorResource < JSONAPI::Resource
   attributes :id, :name
   model_name 'Person'
@@ -244,7 +257,7 @@ class AuthorResource < JSONAPI::Resource
 
   def self.find(attrs, context = nil)
     authors = context.current_user.find_authors(attrs)
-    
+
     return authors.map do |author|
       self.new(author)
     end
@@ -254,11 +267,11 @@ end
 
 ### Controllers
 
-JSONAPI::Resources provides a class, `ResourceController`, that can be used as the base class for your controllers. `ResourceController` supports `index`, `show`, `create`, `update`, and `destroy` methods. Just deriving your controller from `ResourceController` will give you a fully functional controller. 
+JSONAPI::Resources provides a class, `ResourceController`, that can be used as the base class for your controllers. `ResourceController` supports `index`, `show`, `create`, `update`, and `destroy` methods. Just deriving your controller from `ResourceController` will give you a fully functional controller.
 
 For example:
 
-```
+```ruby
 class PeopleController < JSONAPI::ResourceController
 
 end
@@ -266,11 +279,11 @@ end
 
 Of course you are free to extend this as needed and override action handlers or other methods.
 
-The context that's used for serialization and resource configuration is set by the controller's `context` method. 
+The context that's used for serialization and resource configuration is set by the controller's `context` method.
 
 For example:
 
-```
+```ruby
 class ApplicationController < JSONAPI::ResourceController
   def context
     {current_user: current_user}
@@ -288,7 +301,7 @@ end
 
 Error codes are provided for each error object returned, based on the error. These errors are:
 
-```
+```ruby
 module JSONAPI
   VALIDATION_ERROR = 100
   INVALID_RESOURCE = 101
@@ -311,18 +324,19 @@ These codes can be customized in your app by creating an initializer to override
 
 ### Serializer
 
-The `ResourceSerializer` can be used to serialize a resource into JSON API compliant JSON. `ResourceSerializer` has a `serialize` method that takes a resource instance to serialize. For example:
+The `ResourceSerializer` can be used to serialize a resource into JSON API compliant JSON. `ResourceSerializer` has a `serialize_to_hash` method that takes a resource instance to serialize. For example:
 
-```
+```ruby
+require 'jsonapi/resource_serializer'
 post = Post.find(1)
-JSONAPI::ResourceSerializer.new.serialize(PostResource.new(post))
+JSONAPI::ResourceSerializer.new.serialize_to_hash(PostResource.new(post))
 ```
 
 This returns results like this:
 
-```
+```ruby
 {
-  posts: [{
+  posts: {
     id: 1,
     title: 'New post',
     body: 'A body!!!',
@@ -332,13 +346,13 @@ This returns results like this:
       tags: [1,2,3],
       comments: [1,2]
     }
-  }]
+  }
 }
-```                 
+```
 
-#### Serialize method options
+#### Serialize_to_hash method options
 
-The serialize method also takes some optional parameters:
+The `serialize_to_hash` method also takes some optional parameters:
 
 ##### `include`
 
@@ -347,7 +361,7 @@ An array of resources. Nested resources can be specified with dot notation.
   *Purpose*: determines which objects will be side loaded with the source objects in a linked section
 
   *Example*: ```include: ['comments','author','comments.tags','author.posts']```
-  
+
 ##### `fields`
 
 A hash of resource types and arrays of fields for each resource type.
@@ -356,9 +370,9 @@ A hash of resource types and arrays of fields for each resource type.
 
   *Example*: ```fields: { people: [:id, :email, :comments], posts: [:id, :title, :author], comments: [:id, :body, :post]}```
 
-```
+```ruby
 post = Post.find(1)
-JSONAPI::ResourceSerializer.new.serialize(PostResource.new(post),
+JSONAPI::ResourceSerializer.new.serialize_to_hash(PostResource.new(post),
         include: ['comments','author','comments.tags','author.posts'],
         fields: {
                  people: [:id, :email, :comments],
@@ -374,12 +388,12 @@ Context data can be provided to the serializer, which passes it to each resource
 #### Routing
 
 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
 
-```
+```ruby
 require 'jsonapi/routing_ext'
 
 Peeps::Application.routes.draw do
@@ -389,7 +403,7 @@ end
 ```
 
 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"}
@@ -427,15 +441,142 @@ will not create any relationship routes.
 
 You can add relationship routes in with `jsonapi_links`, for example:
 
+```ruby
+Rails.application.routes.draw do
+  jsonapi_resources :posts, except: [:destroy] do
+    jsonapi_link :author, except: [:destroy]
+    jsonapi_links :tags, only: [:show, :create]
+  end
+end
+```
+
+This will create relationship routes for author (show and create, but not destroy) and for tags (again show and create, but not destroy).
+
+#### Formatting
+
+JR by default uses some simple rules to format an attribute for serialization. Strings and Integers are output to JSON as is, and all other values have `.to_s` applied to them. This outputs something in all cases, but it is certainly not correct for every situation.
+
+If you want to change the way an attribute is serialized you have a couple of ways. The simplest method is to create a getter method on the resource which overrides the attribute and apply the formatting there. For example:
+
+```
+class PersonResource < JSONAPI::Resource
+  attributes :id, :name, :email
+  attribute :last_login_time
+
+  def last_login_time
+    @object.last_login_time.in_time_zone('Eastern Time (US & Canada)').to_s
+  end
+end
+```
+
+This is simple to implement for a one off situation, but not for example if you want to apply the same formatting rules to all DateTime fields in your system. Another issue is the attribute on the resource will always return a formatted response, whether you want it or not.
+
+##### Value Formatters
+
+To overcome the above limitations JR uses Value Formatters. Value Formatters allow you to control the way values are handled for an attribute. The `format` can be set per attribute as it is declared in the resource. For example:
+
 ```
-      jsonapi_resources :posts, except: [:destroy] do
-        jsonapi_link :author, except: [:destroy]
-        jsonapi_links :tags, only: [:show, :create]
+class PersonResource < JSONAPI::Resource
+  attributes :id, :name, :email
+  attribute :last_login_time, format: :date_with_timezone
+end
+```
+
+A Value formatter has a `format` and an `unformat` method. Here's the base ValueFormatter and DefaultValueFormatter for reference:
+
+```
+module JSONAPI
+  class ValueFormatter < Formatter
+    class << self
+      def format(raw_value, source, context)
+        super(raw_value)
+      end
+
+      def unformat(value, resource_klass, context)
+        super(value)
       end
+      ...
+    end
+  end
+end
 
+class DefaultValueFormatter < JSONAPI::ValueFormatter
+  class << self
+    def format(raw_value, source, context)
+      case raw_value
+        when String, Integer
+          return raw_value
+        else
+          return raw_value.to_s
+      end
+    end
+  end
+end
 ```
 
-This will create relationship routes for author (show and create, but not destroy) and for tags (again show and create, but not destroy).
+You can also create your own Value Formatter. Value Formatters must be named with the `format` name followed by `ValueFormatter`, i.e. `DateWithTimezoneValueFormatter` and derive from `JSONAPI::ValueFormatter`. It is recommended that you create a directory for your formatters, called `formatters`.
+
+The `format` method is called by the ResourceSerializer as is serializing a resource. The format method takes the `raw_value`, `source`, and `context` parameters. `raw_value` is the value as read from the model, `source` is the resource instance itself, and `context` is the context of the current user/request. From this you can base the formatted version of the attribute on other values on the resource or the current context.
+
+The `unformat` method is called when processing the request. Each incoming attribute (except `links`) are run through the `unformat` method. The `unformat` method takes the `value`, `resource_klass`, and `context` parameters. `value` is the value as it comes in on the request, `resource_klass` is the resource that is being updated or created, and `context` is the context of the current user/request. This allows you process the incoming value to alter its state before it is stored in the model. By default no processing is applied.
+
+###### Use a Different Default Value Formatter
+
+Another way to handle formatting is to set a different default value formatter. This will affect all attributes that do notw have a `format` set. You can do this by overriding the `default_attribute_options` method for a resource (or a base resource for a system wide change).
+
+```
+  def default_attribute_options
+    {format: :my_default}
+  end
+```
+
+and
+
+```
+class MyDefaultValueFormatter < JSONAPI::ValueFormatter
+  class << self
+    def format(raw_value, source, context)
+      case raw_value
+        when String, Integer
+          return raw_value
+        when DateTime
+          return raw_value.in_time_zone('Eastern Time (US & Canada)').to_s
+        else
+          return raw_value.to_s
+      end
+    end
+  end
+end
+```
+
+This way all DateTime values will be formatted to display in the specified timezone.
+
+#### Key Format
+
+JSONAPI is agnostic on the format of the keys used in the responses. By default JR uses underscored keys which match the attribute names used by rails models.  This can be changed by specifying a different key formatter.
+
+For example to use camel cased keys with an initial lowercase character (JSON's default) create an initializer and add the following:
+
+```
+JSONAPI.configure do |config|
+  # built in key format options are :underscored_key, :camelized_key and :dasherized_key
+  config.json_key_format = :camelized_key
+end
+```
+
+This will cause the serializer to use the CamelizedKeyFormatter. Besides UnderscoredKeyFormatter and CamelizedKeyFormatter JR defines the DasherizedKeyFormatter. You can also create your own KeyFormatter, for example:
+
+```
+class UpperCamelizedKeyFormatter < JSONAPI::KeyFormatter
+  class << self
+    def format(key)
+      super.camelize(:upper)
+    end
+  end
+end
+```
+
+You would specify this in `JSONAPI.configure` as `:upper_camelized`.
 
 ## Contributing
 

data/lib/jsonapi/association.rb

@@ -1,5 +1,7 @@
 module JSONAPI
   class Association
+    attr_reader :primary_key, :acts_as_set, :type, :key, :options, :name, :class_name
+
     def initialize(name, options={})
       @name          = name.to_s
       @options       = options
@@ -8,27 +10,11 @@ module JSONAPI
       @acts_as_set   = options.fetch(:acts_as_set, false) == true
     end
 
-    def key
-      @key
-    end
-
-    def primary_key
-      @primary_key
-    end
-
-    def acts_as_set
-      @acts_as_set
-    end
-
-    def serialize_type_name
-      @serialize_type_name
-    end
-
     class HasOne < Association
       def initialize(name, options={})
         super
-        class_name = options.fetch(:class_name, name.to_s.capitalize)
-        @serialize_type_name = class_name.underscore.pluralize.to_sym
+        @class_name = options.fetch(:class_name, name.to_s.capitalize)
+        @type = class_name.underscore.pluralize.to_sym
         @key ||= "#{name}_id".to_sym
       end
     end
@@ -36,8 +22,8 @@ module JSONAPI
     class HasMany < Association
       def initialize(name, options={})
         super
-        class_name = options.fetch(:class_name, name.to_s.capitalize.singularize).to_sym
-        @serialize_type_name = class_name.to_s.underscore.pluralize.to_sym
+        @class_name = options.fetch(:class_name, name.to_s.capitalize.singularize)
+        @type = class_name.underscore.pluralize.to_sym
         @key ||= "#{name.to_s.singularize}_ids".to_sym
       end
     end

data/lib/jsonapi/configuration.rb

@@ -0,0 +1,27 @@
+require 'jsonapi/formatter'
+
+module JSONAPI
+  class Configuration
+    attr_reader :json_key_format, :key_formatter
+
+    def initialize
+      #:underscored_key, :camelized_key, :dasherized_key, or custom
+      self.json_key_format = :underscored_key
+    end
+
+    def json_key_format=(format)
+      @json_key_format = format
+      @key_formatter = JSONAPI::Formatter.formatter_for(format)
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  @configuration ||= Configuration.new
+
+  def self.configure
+    yield(@configuration)
+  end
+end

data/lib/jsonapi/error_codes.rb

@@ -10,6 +10,8 @@ module JSONAPI
   COUNT_MISMATCH = 108
   KEY_ORDER_MISMATCH = 109
   KEY_NOT_INCLUDED_IN_URL = 110
+  INVALID_INCLUDE = 112
+  RELATION_EXISTS = 113
 
   RECORD_NOT_FOUND = 404
   LOCKED = 423

data/lib/jsonapi/exceptions.rb

@@ -30,6 +30,32 @@ module JSONAPI
       end
     end
 
+    class HasManyRelationExists < Error
+      attr_accessor :id
+      def initialize(id)
+        @id = id
+      end
+
+      def errors
+        [JSONAPI::Error.new(code: JSONAPI::RELATION_EXISTS,
+                            status: :bad_request,
+                            title: 'Relation exists',
+                            detail: "The relation to #{id} already exists.")]
+      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)
@@ -89,6 +115,21 @@ module JSONAPI
       end
     end
 
+    class InvalidInclude < Error
+      attr_accessor :association, :resource
+      def initialize(resource, association)
+        @resource = resource
+        @association = association
+      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}")]
+      end
+    end
+
     class ParametersNotAllowed < Error
       attr_accessor :params
       def initialize(params)