rest_model 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+.rvmrc
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/Guardfile

@@ -0,0 +1,7 @@
+guard 'rspec', cli: '--color' do
+  watch(%r{spec/spec_helper.rb})     {"spec"}
+  watch(%r{^config\/(.*\/)*.*\.rb$}) {"spec"}
+
+  watch(%r{^spec/.+_spec\.rb})
+  watch(%r{^lib/(.+)\.rb}) {|m| "spec/#{m[1]}_spec.rb"}
+end

data/README.md

@@ -0,0 +1,237 @@
+# RestModel
+
+**Map from one or more input hashes** to instances of your model classes.
+
+**Map to restful responses** from these model instances. (Some hypermedia magic happens here).
+
+## Usage
+
+### Input hash to model
+
+Given you have:
+
+    input = {
+      "result" => [
+        {
+          "id"       => 1938713897398,
+          "login"    => "jsmith180",
+          "username" => "John Smith",
+          "personal_info" => {
+            "birth_date"      => "1999-02-10",
+            "registered_date" => "2015-04-05"
+          }
+        },
+        {
+          "id"       => 92171987391873,
+          "login"    => "john_appleseed",
+          "username" => "John Appleseed",
+          "personal_info" => {
+            "birth_date"      => "1999-02-10",
+            "registered_date" => "2015-04-05"
+          }
+        }
+      ]
+    }
+
+And you want to transform this input in some instances of a `class User;   attr_accessor :id, :login, :name, :birth;   end`
+
+With RestModel you can parse the input to instances of `User`:
+
+    users = User.parse(input, :result)  # starts looking input hash from 'result' key
+
+Just define your `User` class like this:
+
+    class User < RestModel
+      id
+      property :login
+      property :name,  field: :username                  # input hash key is different from resource key
+      property :birth, field: 'personal_info/birth_date' # digg hash path defined by '/', the last being the key
+    end
+
+### Model instances array to restful response hash
+
+    User.resources(users)
+=>
+
+    {
+      entries: [
+        {
+          id:    1938713897398,
+          login: "jsmith180",
+          name:  "John Smith",
+          birth: "1999-02-10",
+          href:  "http://app/api/users/1938713897398"
+        },
+        {
+          id:    92171987391873,
+          login: "john_appleseed",
+          name:  "John Appleseed",
+          birth: "1999-02-10",
+          href:  "http://app/api/users/92171987391873"
+        }
+      ]
+    }
+
+### Model instance to restful response hash
+
+    user.resource
+=>
+
+    {
+      id:    1938713897398,
+      login: "jsmith180",
+      name:  "John Smith",
+      birth: "1999-02-10",
+      href:  "http://app/api/users/1938713897398"
+    }
+
+## Embedding other resources
+
+### [embeds_one](https://github.com/rodrigues/rest_client/tree/master/examples/embeds_one)
+
+    class Customer < RestModel
+      id field: 'cust_id'
+      embeds_one :address
+    end
+
+    class Address < RestModel
+      property :street,
+      property :number, field: 'n'
+      properties :city, :state, :country
+    end
+
+    {
+      id:    1938713897398,
+      address: {
+        street:  'rest_client st.',
+        number:  '39',
+        city:    'hashland',
+        state:   'std',
+        country: 'ruby'
+      },
+      href:  "http://app/api/users/1938713897398"
+    }
+
+### [embeds_many](https://github.com/rodrigues/rest_client/tree/master/examples/embeds_many)
+
+    class OrderItems < RestModel
+      property :item_id,    id: true      # default serialization: String
+      property :quantity,   type: Integer
+      property :unit_price, type: Float
+      property :amount,     type: Float
+    end
+
+    class Order < RestModel
+      id
+      embeds_many :items, class: OrderItems
+    end
+
+    {
+      id: 739819813719387,
+      items: [
+        {
+          item_id:    1738917139871,
+          quantity:   18,
+          unit_price: 0.2,
+          amount:     3.6
+        },
+        {
+          item_id:    3987187398782,
+          quantity:   1,
+          unit_price: 39.9,
+          amount:     39.9
+        }
+      ]
+    }
+
+## Relations
+
+### has_one
+### has_many
+### belongs_to
+
+    class User < RestModel
+      id
+      property   :login
+      has_one    :avatar
+      has_many   :achievements
+      belongs_to :guilda
+    end
+
+    {
+      id:    19837139879,
+      login: 'jsmith180',
+      link: [
+        {
+          rel:  'avatar',
+          href: 'http://app/api/users/19837139879/avatar'
+        },
+        {
+          rel:  'achievements',
+          href: 'http://app/api/users/19837139879/achievements'
+        },
+        {
+          rel:  'guilda',
+          href: 'http://app/api/users/19837139879/guilda
+        }
+      ]
+    }
+
+### embedding relations
+
+If you want your api to handle `http://app/api/users/19371897318937?include[]=avatar&include[]=guilda`
+
+    user = User.parse(input, include: [avatar_input, guilda_input]).first
+
+    {
+      id:    19837139879,
+      login: 'jsmith180',
+      avatar: {
+        name:   'K1ll3r',
+        specie: 'WTF'
+      },
+      guilda: {
+        name: 'K1ll3rs'
+      },
+      link: [
+        {
+          rel:  'achievements',
+          href: 'http://app/api/users/19837139879/achievements'
+        }
+      ]
+    }
+
+### [See more examples here](https://github.com/rodrigues/rest_client/tree/master/examples).
+
+## Installation
+
+    gem install rest_model
+
+## Maintainers
+
+* [Victor Rodrigues](http://github.com/rodrigues)
+* [Vinicius Higa](http://github.com/viniciushiga)
+* [William "Kina"](http://github.com/kina)
+
+## License
+
+(The 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/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/examples/all.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+
+$:.push 'examples'; require 'helper'
+
+Dir["examples/*/**.rb"].each do |file|
+  [:Root, :Item, :Customer, :Entry, :Service].each do |klass|
+    Object.send(:remove_const, klass) if Object.const_defined? klass
+  end
+
+  puts "\n\nexample file: #{file}\n\n"
+  load file
+end

data/examples/embeds_many/invisible.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  property    :key,    id: true
+  property    :locale, visible: false
+  embeds_many :names,  class_name: 'Hash', visible: false
+  property    :name,   values: proc {names[locale]}
+end
+
+names = {'en' => 'Woot', 'pt-BR' => 'Úia', 'es' => 'Me gusta'}
+
+@root = Root.from_source(locale: 'pt-BR', key: 19190839, names: names).first
+
+inspect_rest_model(@root)

data/examples/embeds_many/simple.rb

@@ -0,0 +1,13 @@
+$:.push 'examples'; require 'helper'
+
+class Item < RestModel
+  property :id, type: Integer
+end
+
+class Root < RestModel
+  embeds_many :items
+end
+
+@root = Root.parse({items: [{id: 2000}, {id: 2001}]}).first
+
+inspect_rest_model(@root)

data/examples/embeds_many/with_array.rb

@@ -0,0 +1,10 @@
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  embeds_many :items, class_name: :array
+end
+
+@root = Root.new
+@root.items = ["a", "b"]
+
+inspect_rest_model(@root)

data/examples/embeds_many/with_class_name.rb

@@ -0,0 +1,13 @@
+$:.push 'examples'; require 'helper'
+
+class Entry < RestModel
+  property :id, type: Integer
+end
+
+class Root < RestModel
+  embeds_many :items, class_name: :entry
+end
+
+@root = Root.parse({items: [{id: 2000}]}).first
+
+inspect_rest_model(@root)

data/examples/embeds_many/with_fields.rb

@@ -0,0 +1,9 @@
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  embeds_many :items, fields: [:item1, :item2, :item3]
+end
+
+@root = Root.parse({item1: "i1", item2: "i2", item3: "i3"}).first
+
+inspect_rest_model(@root)

data/examples/embeds_many/with_if.rb

@@ -0,0 +1,16 @@
+$:.push 'examples'; require 'helper'
+
+class Item < RestModel
+  property :id
+end
+
+class Root < RestModel
+  property :id
+  embeds_many :items, if: proc {id == "10"}
+end
+
+@root_with_items = Root.parse({id: 10, items: [{id: 2000}]}).first
+inspect_rest_model(@root_with_items)
+
+@root_without_items = Root.parse({id: 1, items: [{id: 2000}]}).first
+inspect_rest_model(@root_without_items)

data/examples/embeds_many/with_nil_value.rb

@@ -0,0 +1,12 @@
+$:.push 'examples'; require 'helper'
+
+class Item < RestModel
+  property :id
+end
+
+class Root < RestModel
+  embeds_many :items
+end
+
+@root = Root.new
+inspect_rest_model(@root)

data/examples/embeds_many/with_start_key.rb

@@ -0,0 +1,13 @@
+$:.push 'examples'; require 'helper'
+
+class Item < RestModel
+  property :id, field: :item_id
+end
+
+class Root < RestModel
+  embeds_many :items, start_key: 'detalhe.itens'
+end
+
+@root = Root.parse({"detalhe" => {"itens" => [{item_id: 2000}]}}).first
+
+inspect_rest_model(@root)

data/examples/embeds_one/flattened.rb

@@ -0,0 +1,12 @@
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  embeds_one :item, start_key: ""
+end
+
+class Item < RestModel
+  property :id
+end
+
+@root = Root.parse({id: 2000}).first
+inspect_rest_model(@root)

data/examples/embeds_one/simple.rb

@@ -0,0 +1,12 @@
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  embeds_one :item
+end
+
+class Item < RestModel
+  properties :id, :name
+end
+
+@root = Root.parse({item: {id: 2000}}).first
+inspect_rest_model(@root)

data/examples/embeds_one/with_class_name.rb

@@ -0,0 +1,12 @@
+$:.push 'examples'; require 'helper'
+
+class Entry < RestModel
+  property :id
+end
+
+class Root < RestModel
+  embeds_one :item, class_name: :entry
+end
+
+@root = Root.parse({item: {id: 2000}}).first
+inspect_rest_model(@root)

data/examples/embeds_one/with_if.rb

@@ -0,0 +1,16 @@
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  property :id
+  embeds_one :item, if: proc {id == "1"}
+end
+
+class Item < RestModel
+  property :id
+end
+
+@root_with_item = Root.parse({id: 1, item: {id: 2000}}).first
+inspect_rest_model(@root_with_item)
+
+@root_without_item = Root.parse({id: 100, item: {id: 2000}}).first
+inspect_rest_model(@root_without_item)

data/examples/embeds_one/with_start_key.rb

@@ -0,0 +1,12 @@
+$:.push 'examples'; require 'helper'
+
+class Root < RestModel
+  embeds_one :item, start_key: 'ugly_nesting_key'
+end
+
+class Item < RestModel
+  property :id
+end
+
+@root = Root.parse({'ugly_nesting_key' => {id: 2000}}).first
+inspect_rest_model(@root)

data/examples/has_many/simple.rb

@@ -0,0 +1,28 @@
+$:.push 'examples'; require 'helper'
+
+class Service < RestModel
+  property :name
+  belongs_to :customer
+end
+
+class Billing < RestModel
+  property :login
+  belongs_to :customer
+end
+
+class Developer < RestModel
+  property :login
+  belongs_to :customer
+end
+
+class Customer < RestModel
+  id field: :customer_id, type: Integer
+  property :login
+  has_many :services
+  has_one :billing
+  has_one :devops, class_name: :developer
+end
+
+@root = Customer.parse({customer_id: 123, login: 'jackiechan2010'}).first
+
+inspect_rest_model(@root)

data/examples/helper.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+$:.push 'lib'; require 'rest_model'
+
+def inspect_rest_model(element)
+  puts "instance:  #{element.inspect}"
+  puts "resource:  #{element.resource}"
+  puts "to_source: #{element.to_source}"
+end

data/examples/initialize/embeds_many.rb

@@ -0,0 +1,25 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :name
+  embeds_many :phones
+end
+
+class Phone < RestModel
+  properties :number, :extension
+end
+
+@root = Customer.new({
+  name: "Jackie Chan",
+  phones: [
+    {
+      number: "2980319083",
+      extension: "1398"
+    },
+    {
+      number: "2979139332",
+      extension: "1011"
+    }
+  ]})
+
+inspect_rest_model(@root)

data/examples/initialize/embeds_many_array.rb

@@ -0,0 +1,9 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :name
+  embeds_many :phones, class_name: :array
+end
+
+@root = Customer.new({name: "Jackie Chan", phones: ["1391938", "893271984"]})
+inspect_rest_model(@root)

data/examples/initialize/embeds_one.rb

@@ -0,0 +1,19 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :name
+  embeds_one :address
+end
+
+class Address < RestModel
+  properties :street, :number
+end
+
+@root = Customer.new({
+  name: "Jackie Chan",
+  address: {
+    street: "Aurora St",
+    number: 666
+  }})
+
+inspect_rest_model(@root)

data/examples/initialize/simple.rb

@@ -0,0 +1,8 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :name
+end
+
+@root = Customer.new(name: "Jackie Chan")
+inspect_rest_model(@root)

data/examples/properties/array_serialization.rb

@@ -0,0 +1,8 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :products, type: Enumerable
+end
+
+@root = Customer.parse({products: ['a', 'b', 'c']}).first
+inspect_rest_model(@root)

data/examples/properties/collections.rb

@@ -0,0 +1,11 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :login
+end
+
+@customers = Customer.parse([{login: "jackiechan2010"},
+                             {login: "brucelee"},
+                             {login: "vcr2"}])
+
+@customers.map(&method(:inspect_rest_model))

data/examples/properties/simple.rb

@@ -0,0 +1,8 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :login
+end
+
+@root = Customer.parse({login: 'jackiechan2010'}).first
+inspect_rest_model(@root)

data/examples/properties/with_field.rb

@@ -0,0 +1,8 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :login, field: :customer_login
+end
+
+@root = Customer.parse({customer_login: 'jackiechan2010'}).first
+inspect_rest_model(@root)

data/examples/properties/with_field_path.rb

@@ -0,0 +1,8 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :login, field: 'hidden.login'
+end
+
+@root = Customer.parse({"hidden" => {"login" => 'jackiechan2010'}}).first
+inspect_rest_model(@root)

data/examples/properties/with_id.rb

@@ -0,0 +1,8 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  id
+end
+
+@root = Customer.parse({id: 2000}).first
+inspect_rest_model(@root)

data/examples/properties/with_if.rb

@@ -0,0 +1,21 @@
+$:.push 'examples'; require 'helper'
+
+class Customer < RestModel
+  property :login
+  property :password
+  property :description, if: proc {password == "abc"}
+end
+
+@root_with_description = Customer.parse({
+  login: 2000,
+  password: "abc",
+  description: "description"}).first
+
+inspect_rest_model(@root_with_description)
+
+@root_without_description = Customer.parse({
+  login: 2000,
+  password: "abcd",
+  description: "some text II"}).first
+
+inspect_rest_model(@root_without_description)

data/examples/properties/with_key_converter.rb

@@ -0,0 +1,18 @@
+$:.push 'examples'; require 'helper'
+
+module Upcasing
+  def self.call(keys)
+    keys.map {|key| key.to_s.upcase}
+  end
+end
+
+RestModel::Configuration.configure do |c|
+  c.convert_input_keys = Upcasing
+end
+
+class Customer < RestModel
+  property :login
+end
+
+@root = Customer.parse({"LOGIN" => 'jackiechan2010'}).first
+inspect_rest_model(@root)