api_resource 0.6.21 → 0.6.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 36c5282462a20c9ac625c83f0c8b0c4135c459de
-  data.tar.gz: cb4fc1a93be1e17ec2e7eaa78e4e4d9206c79211
+  metadata.gz: 7509a2d4163d8d10f94db97575b59deec95663a2
+  data.tar.gz: a540de64f15a6196656ca31b43efdee89c816c66
 SHA512:
-  metadata.gz: b051f1d5e8e30d08560ce740386431a8ce4afe39927e79e5b2a732fd562bf307f42d08589e86cdb7b32ed2850d2108965297cb657a7096f394042e45f814675e
-  data.tar.gz: a00eb0d1a846aa56090cae8ccbae5874051647dbcb45d71428d744a6270632b7aed705648dbc82cf253b00a01708fdacf76ddc7b3c89c187ce0aaa61f87220c0
+  metadata.gz: e1860666ecc1aa458a8f35121c6b98017af00161f1ce418476d12c823efa77b4f5e19b24ba6c559b9855cfccbe9ec1827d37d5c3f12400a1bedbf3aadf282a20
+  data.tar.gz: 9d22a6386bc3f13727f7a3e2ea56112b07012874237f340b78b77d5b07a7422c009f160ecb01a0311c6ffa341ea24f8fa63f1595b2137f815d8b8a9607ab7c0a

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    api_resource (0.6.20)
+    api_resource (0.6.21)
       activemodel
       colorize
       differ

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ethan Langevin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -2,23 +2,30 @@
 
 [![Build Status](https://travis-ci.org/LifebookerInc/api_resource.png)](https://travis-ci.org/LifebookerInc/api_resource)
 
-## Installation
+ApiResource is an ActiveModel-compatible library for retrieving and
+persisting data via APIs
 
-Add this line to your application's Gemfile:
+## Getting Started
 
-    gem 'api_resource'
+1. Add this line to your application's Gemfile:
 
-And then execute:
+        gem 'api_resource'
 
-    $ bundle
+1. And then execute:
 
-Or install it yourself as:
+        $ bundle
 
-    $ gem install api_resource
+1. Follow our {file:docs/GettingStarted.md Getting Started Guide} to learn more about how to use ApiResource
 
-## Usage
+## Read more about some of the core concepts in ApiResource
+
+### {file:docs/ResourceDefinition.md The Resource Definition}
+### {file:docs/Attributes.md Attributes}
+### {file:docs/Relationships.md Relationships}
+### {file:docs/Retrieval.md Retrieving Records}
+### {file:docs/Serialization.md Serialization}
+### {file:docs/Caching.md Caching}
 
-TODO: Write usage instructions here
 
 ## Contributing
 

data/docs/Attributes.md

@@ -0,0 +1,64 @@
+# Attributes
+
+Attributes are read from the Server application's
+{file:docs/ResourceDefinition.md Resource Definition}.
+
+## Visibility
+
+### Public
+
+Can read and write, data is sent to the server if it has changed
+
+### Protected
+
+Can read only.  Cannot set or mass-assign
+
+    # Resource definition
+    # {
+    #   ...
+    #   protected : [
+    #     ['updated_at', 'time']
+    #   ]
+    #   ...
+    # }
+
+    Resource::Person.new(updated_at: Time.now) # => Raises error
+    resource = Resource::Person.new
+    resource.updated_at = Time.now #=> Raises error
+
+### Private
+
+Field is not even definted or included in the
+{file:docs/ResourceDefinition.md Resource Definition}.  For more
+info see {http://path/to/server/docs ApiResourceServer ApiResource Server}
+
+
+## Typecasting
+
+ApiResource supports the following types:
+
+1. Array
+1. Boolean
+1. Date
+1. Float
+1. Integer
+1. String
+1. Time
+
+Attributes are given a type in the
+{file:docs/ResourceDefinition.md Resource Definition}.  For more
+info see {http://path/to/server/docs ApiResourceServer ApiResource Server}
+
+## Dirty Tracking
+
+ApiResource::Base includes ActiveModel::Dirty and uses Dirty Tracking to
+determine which attributes to send to the server on save.  Only attributes
+that have changed are sent to the server.
+
+    person = Resource::Person.find(1)
+    person.attributes
+    # => { first_name: 'Aaron', last_name: 'Burr', ...}
+    person.last_name = 'Copeland'
+
+    person.save
+    # PUT /people/1.json { person: { last_name: 'Copeland' } }

data/docs/Caching.md

@@ -0,0 +1,45 @@
+# Caching
+
+Caching is implemented at the connection level and caches the
+respone body and headers of any GET request made while caching
+is active for the period specified
+
+## Where is it cached?
+
+By default we use Rails.cache
+
+    # Configure the cache to use a MemoryStore
+    ApiResource::Base.cache = ActiveSupport::Cache::MemoryStore.new
+
+
+## Activating caching globally
+
+This will cache all GET requests for 30 seconds
+
+    ApiResource::Base.ttl = 30.seconds
+
+## Activating caching for a given find call
+
+    Resource::Person.born_on(Date.today).expires_in(30.seconds).all
+
+
+## Cache expiration
+
+    Resource::Person.born_on(Date.today).expires_in(30.seconds).all
+
+    # no HTTP request here
+    Resource::Person.born_on(Date.today).expires_in(30.seconds).all
+
+    sleep(30)
+
+    # cache has expired - new HTTP Request
+    Resource::Person.born_on(Date.today).expires_in(30.seconds).all
+
+
+## Differing cache times for the same URL
+
+Cache requests are specific to the cache interval specified.  For example,
+if a find with a 60 second TTL and then another with a 30 second TTL will
+make two calls
+
+

data/docs/GettingStarted.md

@@ -0,0 +1,149 @@
+# Getting Started with ApiResource
+
+## Creating a model in your Client application
+
+All of your models will extend {ApiResource::Base}
+
+    # This must be loaded explicitly or created in a directory that is
+    # autoloaded
+
+    # lib/resources/person.rb
+    module Resources
+      class Person < ApiResource::Base
+      end
+    end
+
+## Adding a resource definition in your Server application
+
+On the server-side, you will need to activate the resource
+
+    # app/modeperson.rb
+    class Person < ActiveRecord::Base
+
+      # this gives Person access to the methods necessary
+      # to create a resrouce definition
+      include LifebookerCommon::Model::Resource
+
+      # Example attributes
+      #
+      # :first_name, :last_name, :birthday
+
+      # Example validation
+      #
+      validates :birthday,
+        presence: true
+
+    end
+
+Read more about {file:docs/ResourceDefinition.md Resource Definitions}
+
+## Adding basic routes and controller actions to your Server application
+
+    # config/routes.rb
+    resources :people
+
+    # app/controllers/people_controller.rb
+    class PeopleController < ApplicationController
+
+      respond_to :json
+
+      # GET /people/new
+      def new
+        respond_with(Person.resource_definition)
+      end
+
+      # GET /people
+      def index
+        respond_with(Person.all)
+      end
+
+      # GET /people/:id
+      def show
+        @person = Person.find(params[:id])
+        respond_with(@person)
+      end
+
+      # POST /people
+      def create
+        @person = Person.create(params[:person])
+        respond_with(@person)
+      end
+
+      # PUT /people/:id
+      def update
+        @person = Person.find(params[:id])
+        @person.update_attributes(params[:person])
+        respond_with(@person)
+      end
+
+      # DELETE /people/:id
+      def destory
+        @person = Person.find(params[:id])
+        @person.destory
+        respond_with(@person)
+      end
+    end
+
+## Creating a new record in your Client application
+
+ApiResource knows about your Server model's attributes through its
+{file:docs/ResourceDefinition.md Resource Definition}, so you can just
+set its attributes and call {#save}
+
+It attempts to replicate the behaviors of ActiveRecord as closely as possible
+
+    # in any part of your Client application
+    @person = Resources::Person.new(first_name: 'Aaron', last_name: 'Burr')
+    @person.save #=> true/false
+
+    # if we have errors
+    @person.errors #=> ActiveModel::Errors
+    @person.errors.full_messages #=> ['Birthday is required.']
+
+Read more about {file:docs/Persistance.md Persistance}
+
+## Finding a single record in your Client application
+
+    # raises ApiResource::ResourceNotFound if no Person is found on
+    # the server and a 404 is returned
+    #
+    # GET /people/#{params[:id]}.json
+    @person = Resource::Person.find(params[:id])
+
+## Finding multiple records in your Client application
+
+The query interface mimics ActiveRecord/Arel and reads scopes from the
+{file:docs/ResourceDefinition.md Resource Definitions}
+
+    # GET /people.json
+    @people = Resource::Person.all # all people
+
+    # GET /people.json?first_name=Aaron
+    @people = Resource::Person.where(first_name: 'Aaron')
+    #=> ApiResource::ScopeCondition - Loaded on demand when you start
+    # iterating through the resource (e.g. @people.each {...})
+
+For more information see {file:docs/Retrieval.md#scopes Scopes}
+
+## Updating a record
+
+To update, you just find one or more records and call
+{ApiResource::Base#update_attributes #update_attributes} on each record
+
+    @person = Resource::Person.find(1)
+    @person.update_attributes(
+      first_name: 'Joseph',
+      last_name: 'Stalin',
+      birthday: nil
+    )
+    # => true/false
+
+    @person.errors.full_messages # => ['Birthday is required.']
+
+## Deleting a record
+
+To delete, just find a record and call {ApiResource::Base#destroy #destroy}
+on it
+
+    @person = Resource::Person.find(1)
+    @person.destroy # => true/false

data/docs/Relationships.md

@@ -0,0 +1,136 @@
+# Relationships
+
+ApiResource mimics ActiveRecord's relationships, but loads the data via an
+API or instantiates a record when data is nested
+
+## There are 3 ways to include associated data in a response for APIResource
+
+The proper approach will depend on the specifics of the Server and Client
+applications.  For example, if an associated resource is used just about
+every time the parent is retrieved, it makes sense to nest it.
+
+In general, nesting increases the overall complexity of the Server app and
+slows it down though, so it should be used with caution
+
+Models in the Server application
+
+    class Person < ActiveRecord::Base
+      belongs_to :state
+      has_many :weapons, through: :person_weapons
+    end
+
+    class PersonWeapon < ActiveRecord::Base
+      belongs_to :weapon
+      belongs_to :person
+    end
+
+    class Weapon < ActiveRecord::Base
+      scope :sharp, -> { where(sharp: true) }
+    end
+
+    class State < ActiveRecord::Base
+    end
+
+The Server application would need to have Controllers defined to expose these
+models and their {file:docs/ResourceDefinition.md Resource Definitions}.  For
+an example of that visit {file:docs/GettingStarted.md Getting Started}
+
+
+1. Include the data nested in the response
+
+        # GET /people/1.json
+
+        # Response
+        {
+          first_name: 'Aaron',
+          last_name: 'Burr',
+          weapons: [
+            { id: 1, name: 'Ax', sharp: true },
+            { id: 2, name: 'Pistol', sharp: false }
+          ],
+          state: { id: 10, name: 'New York' }
+        }
+
+        # in the Client application
+        person = Resource::Person.find(1)
+        person.state.name # => 'New York'
+        person.weapons.length # => 2
+
+        # no additional HTTP calls are made
+
+1. Include a link to the data in the response
+
+        # GET /people/1.json
+
+        # Response
+        {
+          first_name: 'Aaron',
+          last_name: 'Burr',
+          weapons: [ { service_uri: '/people/1/weapons' } ],
+          state: { service_uri: '/states/10' }
+        }
+
+        # in the Client application
+        person = Resource::Person.find(1)
+        person.state.name # => 'New York'
+        person.weapons.length # => 2
+
+        # 2 additional HTTP calls are made
+        # (1 to each :service_uri provided)
+
+1. Include the ids for the associated objects in the response
+
+        # GET /people/1.json
+
+        # Response
+        {
+          first_name: 'Aaron',
+          last_name: 'Burr',
+          weapon_ids: [ 1, 2 ],
+          state_id: 10
+        }
+
+        # in the Client application
+        person = Resource::Person.find(1)
+        person.state.name # => 'New York'
+        person.weapons.length # => 2
+
+        # 2 additional HTTP calls are made
+        # GET /weapons.json?ids[]=1&ids[]=2
+        # and
+        # GET /states/10.json
+
+
+## Applying a scope to a relationship
+
+Any scope on the relationship model can be applied to the relationship and
+will be passed on to the server
+
+*Note:* This does not work with embedded data because it has already
+be loaded with the parent resource
+
+
+    @person = Resource::Person.find(1)
+
+    # GET /people/1/weapons.json
+    @person.weapons
+    # => [ Resource::Weapon(id: 1, name: 'Ax', sharp: true), Resource::Weapon(id: 2, name: 'Pistol', sharp: false) ]
+
+    # GET /people/1/weapons.json?sharp=true
+    @person.weapons.sharp
+    # => [ Resource::Weapon(id: 1, name: 'Ax', sharp: true) ]
+
+## Saving associated records
+
+By default, ApiResource assumes that any modifications to individual records
+in an Association will be saved directly via that record
+
+ApiResource::Base does provide the option to `:include_associations` on save
+to mass-update records.  This includes the data with the parent record's save
+call.
+
+    @person = Resource::Person.find(1)
+
+    @person.state.name = 'I renamed New York'
+    @person.save(include_associations: [:state])
+    # PUT /people.json { state: { name: 'I renamed New York', id: 10 } }

data/docs/ResourceDefinition.md

@@ -0,0 +1,80 @@
+# The Resource Definition
+
+The Resource Definition is the way that the Server application communicates
+the properties and scopes of its models to the Client application
+
+## How do I set this up in my Server application?
+
+Full documentation is available at {http://path/to/server/docs ApiResourceServer}
+
+## Definition Components
+
+### Attributes
+
+Attributes are typically fields in the database, but can be declared using
+`virtual_attribute` in the Server's model as well
+
+#### Visibility
+
+ApiResourceServer hooks into `attr_protected` and provides `attr_private` to
+communicate visibility of different attributes
+
+
+### Scopes
+
+ApiResource also hooks into ActiveRecord's `scope` to communicate
+the models in the Server applications' scopes
+
+### Associations
+
+ApiResource also hooks into ActiveRecord's `has_many`, `belongs_to` and
+`has_one` associations to communicate the models in the Server applications'
+associations
+
+## Exposing the Resource Definition
+
+The Server application is responsible for exposing the Resource Definition
+to the Client application.  It should do so at
+`GET /PLURALIZED_RESOURCE_NAME/new.json`
+
+
+## Examples
+
+See {http://path/to/server/docs ApiResourceServer} for more information
+on declaring your attributes
+
+
+## Final Resource Definition
+
+    {
+      attributes: {
+        public: [
+          ["birthday", Date],
+          ["first_name", "string"],
+          ["last_name", "string"]
+        ],
+        protected: [
+          ["created_at", "time"],
+          ["id", "integer"]
+          ["updated_at", "time"]
+        ]
+      },
+      associations : {
+        belongs_to: {
+          state: {}
+        },
+        has_many: {
+          friends: {}
+        }
+
+      },
+      scopes: {
+        active: {},
+        born_on: { date: :req }
+      }
+
+    }
+
+
+
+