api_resource 0.6.21 → 0.6.22

data/docs/Retrieval.md

@@ -0,0 +1,279 @@
+# Retrieving Records in ApiResource
+
+
+## Finding by id
+
+The simplest way to retrieve a record is by its ID
+
+    Resource::Person.find(1)
+    # GET /people/1.json
+
+## Simple conditions
+
+To add simple query params, you can just use the `.where` method
+
+    Resource::Person.where(first_name: 'Aaron').all
+    # GET /people.json?first_name=Aaron
+
+## Scopes
+
+Scopes must be activated in the Server application and are then read by
+the client application via the
+{file:docs/ResourceDefinition.md Resource Definition}.
+
+### Activating a scope in the Server application
+
+    # app/models/person.rb
+    class Person < ActiveRecord::Base
+
+      include LifebookerCommon::Model::Resource
+
+      scope :birthday_on, -> date {
+       where(birthday: date)
+      }
+
+      scope :aaron, -> {
+        where(name: 'Aaron')
+      }
+
+    end
+
+### Using a scope in the Client application
+
+    # GET /people.json?birthday_on[date]=2014-01-01
+    @people = Resource::Person.birthday_on(Date.parse('2014-01-01'))
+
+    @people.each do |person|
+      ...
+    end
+
+Scopes can be chained together
+
+    # GET /people.json?birthday_on[date]=2014-01-01&aaron=1
+    @people = Resource::Person
+      .birthday_on(Date.parse('2014-01-01'))
+      .aaron
+
+    @people.each do |person|
+      ...
+    end
+
+### Applying scopes in the Client application
+
+ApiResource::Base gives us the ability to apply scopes that are valid
+according to the {file:docs/ResourceDefinition.md Resource Definition}
+directly from params that are passed in
+
+    # In the Client application
+    class PeopleController < ApplicationController
+
+      def index
+        @people = Resource::Person.add_scopes(params)
+      end
+
+    end
+
+This reads the params supplied to the controller to see if there are any
+valid scopes and then applies them.  These scopes follow the same rules
+as the ones that are sent to the server
+
+#### Sequence
+
+1. Client supplies params to our client app
+
+        # curl http://clienthost/people.html?birthday_on[date]=2014-01-01
+
+1. Client controller parses params, passes them to {ApiResource.add_scopes}
+  and creates a ScopeCondition to generate params to the server
+
+1. Resource::Person makes a request to the Server application.  This request
+  has the same parameters as what was passed in to the client application
+  assuming those parameters were valid for a scope
+
+        # GET http://serverhost/people.json?birthday_on[date]=2014-01-01
+
+1. Server application returns the data as JSON and Resource::Person
+  instantiates its records for use in the Client application
+
+### Automatically generated scopes
+
+`api_resource_server` and {ApiResource::Base} automatically provide several
+scopes for all descendants of ActiveRecord::Base and ApiResource::Base
+respectively
+
+#### IDs
+
+You can supply an array of ids to a resource to scope by only resources in
+that set of ids
+
+    # in the Client application
+    Resource::Person.add_scopes(ids: [1, 2, 3])
+    # => GET /people.json?ids[]=1&ids[]=2&ids[]=3
+
+#### Type
+
+In order to limit your scope to a subclass of a class that users Single Table
+Inheritance, you can supply the type
+
+    # in the Server application
+    class Carpenter < Person
+    end
+
+    # in the Client application
+    Resource::Person.type('Carpenter')
+    # => GET /people.json?type=Carpenter
+
+    # back in the Server application Person.add_scopes
+    # converts
+
+    Person.all
+
+    # into
+
+    Carpenter.all
+
+#### Page and PerPage
+
+In order to paginate, you can pass page and per_page scopes into your
+ApiResource::Base subclass
+
+    Resource::Person.per_page(20).page(1)
+
+    # or
+
+    Resource::Person.add_scopes(per_page: 20, page: 1)
+
+    # either of these produce
+    GET /people.json?page=1&per_page=20
+
+In the Server application `add_scopes` will take care of applying
+the pagination using its integration with
+{https://github.com/mislav/will_paginate will_paginate}
+
+In addition, the Server application will include a header denoting
+the number of records in the set so that
+{https://github.com/mislav/will_paginate will_paginate} can
+render its page helpers on the client side
+
+*Note* that in order to enable this feature the Server application
+*must* use `respond_to`
+
+    # in a controller in the Client application
+    @people = Resource::Person.add_scopes(
+      params.merge(page: 2, per_page: 20)
+    )
+
+    # in a view in the Client application
+    - @people.each do |person|
+      %tr
+        %td ...
+    # renders the pagination links
+    = will_paginate(@people)
+
+### Types of scopes
+
+1. Static scopes
+
+        # Server code
+        scope :x, where(x: 'Val')
+        OR
+        scope :x, -> { where(x: 'Val') }
+
+        # Produces request from client
+        Resource::Person.x
+        # ?x=1
+
+1. Scopes with required parameters
+
+        # Server code
+        scope :birthday_between, -> start, end {
+          where("birthday_between ? AND ?", start, end)
+        }
+
+        # Produces request from the client
+        @people = Resource::Person.birthday_between(
+          start: Date.today,
+          end: Date.tomorrow
+        )
+        # ?birthday_between[start]=2014-01-01&birthday_between[end]=2014-01-02
+
+1. Scopes with varargs
+
+        # server code
+        scope :first_name, -> *names {
+          where(first_name: names)
+        }
+
+      # Produces request from the client
+      @people = Resource::Person.first_name('Bill', 'Sue')
+      # ?first_name[]=Bill&first_name[]=Sue
+
+## Including associated data
+
+Oftentimes we will need data from two resources, which would produce n+1 API
+calls unless we sideload our data
+
+### Concept
+
+If, for example we loaded a list of 50 People, but needed their State data we
+might have to make 50 requests to the State API endpoint
+
+### Server application
+
+    # in app/models/person.rb
+    class Person < ActiveRecord::Base
+
+      belongs_to :state
+
+      # Attributes
+      #
+      # :first_name, :last_name, :state_id
+
+    end
+
+    # in app/models/state.rb
+    class State < ActiveRecord::Base
+      # Attributes
+      #
+      # :name
+    end
+
+    # in app/controllers/people_controller.rb
+    def index
+      respond_with(Person.add_scopes(params))
+    end
+
+    # in app/controllers/states_controller.rb
+    def index
+      respond_with(State.add_scopes(params))
+    end
+
+### Client application
+
+    # in lib/resource/state.rb
+    module Resource
+      class State < ApiResource::Base
+      end
+    end
+
+    # in lib/resource/person.rb
+    module Resource
+      class Person < ApiResource::Base
+      end
+    end
+
+    # in a controller
+    @people = Resource::Person.includes(:state)
+
+    # this results in
+    #
+    # GET /people.json
+    #
+    # and
+    #
+    # GET /states.json?ids[]=person1.state_id&ids[]=person2.state_id ...
+
+
+{ApiResource::Base} knows how to include data from any association where
+ids are embedded in the response of the base object and the association
+is present in the {file:docs/ResourceDefinition.md Resource Definition}

data/docs/Serialization.md

@@ -0,0 +1,56 @@
+# Serialization in ApiResource
+
+## Sending Data to Server (JSON)
+
+Data is Serialized using singular resource name as a key, and the attributes as the value.
+
+    # POST /people.json
+
+    # POST body
+    {
+      person: {
+        first_name: "Aaron",
+        last_name: "Burr",
+        birthdate: "1755-02-05"
+      }
+    }
+
+## Retrieving Data From Server
+
+ApiResource expects resources to be at the root of the JSON or XML document
+returned
+
+    # GET /people/1.json
+
+    # Response
+    {
+      first_name: 'Aaron',
+      last_name: 'Burr',
+      birthdate: '1756-02-06'
+    }
+
+    # GET /people.json
+
+    # Response
+    [
+      {
+        first_name: 'Aaron',
+        last_name: 'Burr',
+        birthdate: '1756-02-06'
+      }
+    ]
+
+## Setting the Serializer Format
+
+ApiResource ships with two major Formats: {ApiResource::Formats::JsonFormat}
+and {ApiResource::Formats::XmlFormat}
+
+The default format is `:json`
+
+You can configure your format:
+
+    ApiResource::Base.format = ApiResource::Formats::JsonFormat
+
+    # OR
+
+    ApiResource::Base.format = :xml

data/lib/api_resource/associations/has_many_remote_object_proxy.rb

@@ -7,7 +7,7 @@ module ApiResource
         id_method_name = self.foreign_key_name(assoc_name)
 
         klass.api_resource_generated_methods.module_eval <<-EOE, __FILE__, __LINE__ + 1
-          
+
           def #{id_method_name}
             @attributes_cache[:#{id_method_name}] ||= begin
               # check our attributes first, then go to the remote
@@ -43,7 +43,7 @@ module ApiResource
               :ids => associated_ids
             )
           # next try for a foreign key e.g. /objects.json?owner_id=1
-          elsif self.owner.try(:id).present?
+          elsif self.owner.try(:id).to_i > 0
             self.remote_path = self.klass.collection_path(
               self.owner.class.to_s.foreign_key => self.owner.id
             )

data/lib/api_resource/attributes.rb

@@ -136,8 +136,8 @@ module ApiResource
       # Adds the attribute into some internal data structures but does
       # not define any methods for it
       #
-      # @param  arg [Array] A 1 or 2 element array holding an attribute name and
-      # optionally a type for that attribute
+      # @param  arg [Array] A 1 or 2 element array holding an
+      # attribute name and optionally a type for that attribute
       # @param  access_level [Symbol] Either :protected or :public based on
       # the access level for this attribute
       #
@@ -542,9 +542,21 @@ module ApiResource
 
     def method_missing(sym, *args, &block)
       sym = sym.to_sym
-      if @attributes.keys.symbolize_array.include?(sym)
+
+      # Maybe the resource definition sucks...
+      if self.class.resource_definition_is_invalid?
+        self.class.reload_resource_definition
+      end
+
+      # If we don't respond by now...
+      if self.respond_to?(sym)
+        return self.send(sym, *args, &block)
+      elsif @attributes.keys.symbolize_array.include?(sym)
+        # Try returning the attributes from the attributes hash
         return @attributes[sym]
       end
+
+      # Fall back to class method_missing
       super
     end
 
@@ -680,4 +692,4 @@ module ApiResource
 
   end
 
-end
+end

data/lib/api_resource/base.rb

@@ -31,22 +31,31 @@ module ApiResource
     # => 7) Write documentation
     # => 8) Write Examples
 
-    class_attribute :site, :proxy, :user, :password, :auth_type, :format,
-      :timeout, :open_timeout, :ssl_options, :token, :ttl
+    class_attribute(
+      :site,
+      :proxy,
+      :user,
+      :password,
+      :auth_type,
+      :format,
+      :timeout,
+      :open_timeout,
+      :ssl_options,
+      :token,
+      :ttl,
+      { instance_writer: false, instance_reader: false }
+    )
+    self.format = ApiResource::Formats::JsonFormat
 
-    class_attribute :include_root_in_json
+    class_attribute(:include_root_in_json)
     self.include_root_in_json = true
 
-    class_attribute :include_nil_attributes_on_create
+    class_attribute(:include_nil_attributes_on_create)
     self.include_nil_attributes_on_create = false
 
-    class_attribute :include_all_attributes_on_update
+    class_attribute(:include_all_attributes_on_update)
     self.include_nil_attributes_on_create = false
 
-    class_attribute :format
-    self.format = ApiResource::Formats::JsonFormat
-
-
     delegate :logger, to: ApiResource
 
     class << self
@@ -197,12 +206,12 @@ module ApiResource
       # backwards compatibility
       alias_method :reload_class_attributes, :reload_resource_definition
 
-      # 
+      #
       # Mutex so that multiple Threads don't try to load the resource
       # definition at the same time
-      # 
+      #
       # @return [Mutex]
-      def resource_definition_mutex 
+      def resource_definition_mutex
         @resource_definition_mutex ||= Mutex.new
       end
 
@@ -365,11 +374,15 @@ module ApiResource
 
       # path to find
       def new_element_path(prefix_options = {})
-        File.join(
+        url = File.join(
           self.prefix(prefix_options),
           self.collection_name,
           "new.#{format.extension}"
         )
+        if self.superclass != ApiResource::Base && self.name.present?
+          url = "#{url}?type=#{self.name.demodulize}"
+        end
+        return url
       end
 
       def collection_path(prefix_options = {}, query_options = nil)
@@ -541,6 +554,14 @@ module ApiResource
       self.class.instantiate_record(self.attributes)
     end
 
+    #
+    # Implementation of to_key for use in Rails forms
+    #
+    # @return [Array<Fixnum>,nil] Array wrapped id or nil
+    def to_key
+      [self.id] if self.id.present?
+    end
+
     def update_attributes(attrs)
       self.attributes = attrs
       self.save
@@ -697,9 +718,14 @@ module ApiResource
       path = self.collection_path
       body = self.setup_create_call(*args)
       headers = self.class.headers
-      # make the post call
-      connection.post(path, body, headers).tap do |response|
-        load_attributes_from_response(response)
+
+      # this checks to see if we have uploaded a file
+      # and sets headers accordingly
+      self.with_uploaded_file_format do
+        # make the post call
+        connection.post(path, body, headers).tap do |response|
+          load_attributes_from_response(response)
+        end
       end
     end
 
@@ -724,9 +750,14 @@ module ApiResource
       path = self.element_path(self.id)
       body = self.setup_update_call(*args)
       headers = self.class.headers
-      # We can just ignore the response
-      connection.put(path, body, headers).tap do |response|
-        load_attributes_from_response(response)
+
+      # this checks to see if we have uploaded a file
+      # and sets headers accordingly
+      self.with_uploaded_file_format do
+        # We can just ignore the response
+        connection.put(path, body, headers).tap do |response|
+          load_attributes_from_response(response)
+        end
       end
     end
 
@@ -765,6 +796,54 @@ module ApiResource
       return data
     end
 
+    protected
+
+    #
+    # Are any of our attributes of type File?
+    #
+    # @return [Boolean]
+    def has_file_attribute?
+      self.attributes.values.any?{|val|
+        HTTP::Message.file?(val) ||
+          val.is_a?(ActionDispatch::Http::UploadedFile)
+      }
+    end
+
+    #
+    # Run a block with a given format
+    #
+    # @param  new_format [Module] Format module
+    # @param  &block [Proc] Block to run
+    #
+    # @return [Mixed]
+    def with_format(new_format, &block)
+
+      old_format = self.class.format
+
+      begin
+        self.class.format = new_format
+        yield
+      ensure
+        self.class.format = old_format
+      end
+    end
+
+    #
+    # Wrapper to add the FileUpload format
+    #
+    # @param  &block [Proc] Block to run
+    #
+    # @return [Mixed]
+    def with_uploaded_file_format(&block)
+      if self.has_file_attribute?
+        self.with_format(Formats::FileUploadFormat) do
+          yield
+        end
+      else
+        yield
+      end
+    end
+
     private
 
     def split_options(options = {})