braque 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b7c808e05c6710b54706c5a3dfdcca8a36af7e41
+  data.tar.gz: d90bcc7ed6d6cb29677ea06b92a344a72eb99f5d
+SHA512:
+  metadata.gz: f093efaacf01e01ad2028759609f21768efad162bea40d28e8e0617bbe278ff4338d05be7af922555dff9b96cdf5ccaf744cbe3d29ebf92d1cb35e83fc512d68
+  data.tar.gz: 12acb696429f1f62af2c8983a14b52da695cae0a8584b4626fcd4ac8348c1270379d6d5461e6f4c4d66f47bf5ff751c7fe9f8b7f2888ce276c20619f6cdf95ee

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Dylan Fareed
+
+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

@@ -0,0 +1,67 @@
+# Braque
+
+Braque aims to provide a simple and familiar interface for setting up clients to interact with [Hypermedia (hal+json)](http://stateless.co/hal_specification.html) API services. It is a lightweight wrapper around [Hyperclient](https://github.com/codegram/hyperclient) and [ActiveAttr](https://github.com/cgriego/active_attr).
+
+Braque is an early-stage and exploratory project.
+
+### Model setup
+
+```Braque::Model``` is ActiveSupport concern. You can use Braque::Model to map a remote resource to a class in your application. Do so by including Braque::Model in the class, defining the API service's root url and authentication details, and listing attributes which we expect from the API.
+
+```ruby
+class Article
+  include Braque::Model
+  self.api_root = Rails.application.config_for(:article_service)['url']
+  self.api_token = Rails.application.config_for(:article_service)['token']
+
+  attribute :id
+  attribute :title
+  attribute :body
+  attribute :summary
+  attribute :created_at
+  attribute :updated_at
+end
+```
+
+In a Rails app, you can then use this model simply:
+
+```ruby
+class ArticlesController < ApplicationController
+  before_filter :find_article, except: :index
+
+  def index
+    @articles = Article.list(page: params[:page], size: params[:size])
+  end
+
+  def new
+  end
+
+  def create
+    @article = Article.create params[:article]
+    redirect_to article_path(@article)
+  end
+
+  def show
+  end
+
+  def edit
+  end
+
+  def update
+    @article = @article.save params[:article]
+    redirect_to article_path(id: @article.id)
+  end
+
+  def destroy
+    @article.destroy
+    redirect_to articles_path
+  end
+
+  private
+
+  def find_article
+    @article = Article.find params[:id]
+  end
+end
+
+```

data/lib/braque/collection.rb

@@ -0,0 +1,19 @@
+module Braque
+  module Collection
+    class LinkedArray < Array
+      attr_reader :next_link
+      attr_reader :previous_link
+
+      def initialize(response = [], klass)
+        next_link = response._links.try(:next)
+        previous_link = response._links.try(:prev)
+        retrieved_items = []
+        response.each do |item|
+          retrieved_items << klass.new(item)
+        end
+        @retrieved_items, @next_link, @previous_link = retrieved_items, next_link, previous_link
+        super retrieved_items
+      end
+    end
+  end
+end

data/lib/braque/model.rb

@@ -0,0 +1,61 @@
+module Braque
+  module Model
+    extend ::ActiveSupport::Concern
+    include ::ActiveAttr::Model
+
+    included do
+      def to_param
+        "#{id}"
+      end
+
+      def save(params = {})
+        response = self.class.client.method(self.class.instance_method_name).call(id: id)._patch("#{self.class.instance_method_name}" => params)
+        self.class.new response
+      end
+
+      def destroy
+        response = self.class.client.method(self.class.instance_method_name).call(id: id)._delete
+      end
+
+      class_eval <<-WRITER
+        def self.#{collection_method_name}
+        end
+      WRITER
+    end
+
+    module ClassMethods
+      include Braque::Collection
+      cattr_accessor :api_root
+      cattr_accessor :api_token
+
+      def list(options = {})
+        response = client.method(collection_method_name).call(page: options[:page], size: options[:size])
+        LinkedArray.new response, self
+      end
+
+      def find(id)
+        response = client.method(instance_method_name).call(id: id)
+        new response
+      end
+
+      def create(params = {})
+        response = client.method(collection_method_name).call._post("#{instance_method_name}" => params)
+        new response
+      end
+
+      def collection_method_name
+        name.tableize
+      end
+
+      def instance_method_name
+        collection_method_name.singularize
+      end
+
+      def client
+        Hyperclient.new(api_root) do |client|
+          client.headers['Http-Authorization'] = api_token
+        end
+      end
+    end
+  end
+end

data/lib/braque/version.rb

@@ -0,0 +1,3 @@
+module Braque
+  VERSION = '0.0.1'
+end

data/lib/braque.rb

@@ -0,0 +1,9 @@
+require 'active_support'
+require 'active_attr'
+require 'hyperclient'
+require 'braque/version'
+require 'braque/collection'
+require 'braque/model'
+
+module Braque
+end

data/spec/braque/collection_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+RSpec.describe Braque::Collection do
+  context 'paginate_and_sort in a GravityModel class' do
+    before(:all) do
+      class BraqueClass
+        include ::ActiveAttr::Model
+        include Braque::Collection
+        attribute :id
+        attribute :title
+      end
+
+      class ResponseLinks
+        attr_reader :next
+        attr_reader :prev
+        def initialize(next_str, previous_str)
+          @next = next_str
+          @prev = previous_str
+        end
+      end
+
+      class ResponseCollection < Array
+        attr_reader :_links
+        def initialize(array = [], next_str, previous_str)
+          @_links = ResponseLinks.new next_str, previous_str
+          super array
+        end
+      end
+    end
+
+    context 'LinkedArray' do
+      context '#initialize' do
+        before(:all) do
+          @array = [{ id: 1, title: 'hello' }, { id: 2, title: 'goodbye' }]
+          @response = ResponseCollection.new @array, true, false
+          @linked_array = BraqueClass::LinkedArray.new(@response, BraqueClass)
+        end
+        it 'returns an array of the correct number of items' do
+          expect(@linked_array.count).to eq 2
+        end
+        it 'returns an array of new items based on the calling class' do
+          expect(@linked_array.first.id).to eq 1
+          expect(@linked_array.first.title).to eq @array.first[:title]
+          expect(@linked_array.first.class.name).to eq 'BraqueClass'
+
+          expect(@linked_array[1].id).to eq 2
+          expect(@linked_array[1].title).to eq @array[1][:title]
+          expect(@linked_array[1].class.name).to eq 'BraqueClass'
+        end
+        it 'responds to previous_link with the correct value' do
+          expect(@linked_array).to respond_to(:previous_link)
+          expect(@linked_array.previous_link).to eq false
+        end
+        it 'responds to next_link with the correct value' do
+          expect(@linked_array).to respond_to(:next_link)
+          expect(@linked_array.next_link).to eq true
+        end
+      end
+    end
+  end
+end

data/spec/braque/model_spec.rb

@@ -0,0 +1,159 @@
+require 'spec_helper'
+
+RSpec.describe Braque::Model, type: :model do
+  before(:all) do
+    class Breeze
+      include ::Braque::Model
+      self.api_root = 'http://localhost:9292'
+      self.api_token = 'replace-me'
+      attribute :id
+      attribute :title
+    end
+  end
+
+  let(:root_response) { JSON.parse(File.read 'spec/fixtures/root.json') }
+  let(:collection_response) { JSON.parse(File.read 'spec/fixtures/collection.json') }
+  let(:resource_response) { JSON.parse(File.read 'spec/fixtures/resource.json') }
+  let(:root_request) do
+    WebMock.stub_request(:get, "#{Breeze.api_root}/")
+      .with(headers: { 'Http-Authorization' => Breeze.api_token })
+      .to_return(status: 200, body: root_response)
+  end
+
+  context 'class methods' do
+    it 'responds to find, create, and list' do
+      expect(Breeze).to respond_to(:find, :create, :list)
+    end
+
+    it 'converts the class name into collection_method_name' do
+      expect(Breeze.collection_method_name).to eq 'breezes'
+    end
+
+    it 'converts the class name into instance_method_name' do
+      expect(Breeze.instance_method_name).to eq 'breeze'
+    end
+
+    context '.list' do
+      before(:each) do
+        root_request
+        @collection_request = WebMock.stub_request(:get, "#{Breeze.api_root}/breezes")
+                              .with(headers: { 'Http-Authorization' => Breeze.api_token })
+                              .to_return(status: 200, body: collection_response)
+        @breezes = Breeze.list
+      end
+      it 'performs the API root request' do
+        expect(root_request).to have_been_requested
+      end
+      it 'performs the collection request' do
+        expect(@collection_request).to have_been_requested
+      end
+      it 'returns an array of items' do
+        expect(@breezes.count).to be 1
+        expect(@breezes.first).to be_a_kind_of Breeze
+      end
+      it 'returns items with the correct class' do
+        expect(@breezes.first).to be_a_kind_of Breeze
+      end
+      it 'returns an array of items with the correct attributes' do
+        breeze = @breezes.first
+        expect(breeze.id).to eq collection_response['_embedded']['breezes'].first['id']
+        expect(breeze.title).to eq collection_response['_embedded']['breezes'].first['title']
+      end
+    end
+
+    context '.find' do
+      before(:each) do
+        root_request
+        @resource_request = WebMock.stub_request(:get, "#{Breeze.api_root}/breezes/1")
+                            .with(headers: { 'Http-Authorization' => Breeze.api_token })
+                            .to_return(status: 200, body: resource_response)
+        @breeze = Breeze.find 1
+      end
+      it 'performs the API root request' do
+        expect(root_request).to have_been_requested
+      end
+      it 'performs the resource request' do
+        expect(@resource_request).to have_been_requested
+      end
+      it 'returns an item with the correct class' do
+        expect(@breeze).to be_a_kind_of Breeze
+      end
+      it 'returns an item with the correct attributes' do
+        expect(@breeze.id).to eq resource_response['id']
+        expect(@breeze.title).to eq resource_response['title']
+      end
+    end
+
+    context '.create' do
+      before(:each) do
+        root_request
+        @create_request = WebMock.stub_request(:post, "#{Breeze.api_root}/breezes")
+                          .with(headers: { 'Http-Authorization' => Breeze.api_token })
+                          .to_return(status: 201, body: resource_response)
+        @params = { title: 'What a nice breeze.' }
+        @breeze = Breeze.create(@params)
+      end
+      it 'performs the API root request' do
+        expect(root_request).to have_been_requested
+      end
+      it 'performs the create request' do
+        expect(@create_request).to have_been_requested
+      end
+      it 'returns an item with the correct class' do
+        expect(@breeze).to be_a_kind_of Breeze
+      end
+      it 'returns an item with the correct attributes' do
+        expect(@breeze.id).to eq resource_response['id']
+        expect(@breeze.title).to eq resource_response['title']
+      end
+    end
+  end
+  context 'instance methods' do
+    it 'sets to_param string based on instance.id' do
+      expect(Breeze.new(id: 1).to_param).to eq 1.to_s
+    end
+
+    context '#save' do
+      before(:each) do
+        root_request
+        @save_request = WebMock.stub_request(:patch, "#{Breeze.api_root}/breezes/1")
+                        .with(headers: { 'Http-Authorization' => Breeze.api_token })
+                        .to_return(status: 200, body: resource_response)
+        @params = { title: 'What a nice breeze.' }
+        @breeze = Breeze.new(id: 1).save(@params)
+      end
+      it 'performs the API root request' do
+        expect(root_request).to have_been_requested
+      end
+      it 'performs the save request' do
+        expect(@save_request).to have_been_requested
+      end
+      it 'returns an item with the correct class' do
+        expect(@breeze).to be_a_kind_of Breeze
+      end
+      it 'returns an item with the correct attributes' do
+        expect(@breeze.id).to eq resource_response['id']
+        expect(@breeze.title).to eq resource_response['title']
+      end
+    end
+
+    context '#destroy' do
+      before(:each) do
+        root_request
+        @destroy_request = WebMock.stub_request(:delete, "#{Breeze.api_root}/breezes/1")
+                           .with(headers: { 'Http-Authorization' => Breeze.api_token })
+                           .to_return(status: 200)
+        @resource_request = WebMock.stub_request(:get, "#{Breeze.api_root}/breezes/1")
+                            .with(headers: { 'Http-Authorization' => Breeze.api_token })
+                            .to_return(status: 200, body: resource_response)
+        @breeze = Breeze.new(id: 1).destroy
+      end
+      it 'performs the API root request' do
+        expect(root_request).to have_been_requested
+      end
+      it 'performs the destroy request' do
+        expect(@destroy_request).to have_been_requested
+      end
+    end
+  end
+end

data/spec/fixtures/collection.json

@@ -0,0 +1,23 @@
+{
+   "total_count":1,
+   "total_pages":1,
+   "current_page":1,
+   "_links":{
+      "self":{
+         "href":"http://localhost:9292/breezes"
+      }
+   },
+   "_embedded":{
+      "breezes":[
+         {
+            "id":1,
+            "title":"Southerly Breeze",
+            "_links":{
+               "self":{
+                  "href":"http://localhost:9292/breezes/1"
+               }
+            }
+         }
+      ]
+   }
+}

data/spec/fixtures/resource.json

@@ -0,0 +1,11 @@
+{
+   "id":1,
+   "title":"Southerly Breeze",
+   "created_at":"2015-02-11T18:59:01.669Z",
+   "updated_at":"2015-02-12T00:26:22.255Z",
+   "_links":{
+      "self":{
+         "href":"http://example.org/breezes/1"
+      }
+   }
+}

data/spec/fixtures/root.json

@@ -0,0 +1,18 @@
+{
+   "_links":{
+      "self":{
+         "href":"http://localhost:9292"
+      },
+      "health":{
+         "href":"http://localhost:9292/health"
+      },
+      "breezes":{
+         "href":"http://localhost:9292/breezes{?page,size}",
+         "templated":true
+      },
+      "breeze":{
+         "href":"http://localhost:9292/breezes/{id}",
+         "templated":true
+      }
+   }
+}

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+Dir["#{File.dirname(__FILE__)}/shared/**/*.rb"].each do |file|
+  require file
+end
+
+Dir["#{File.dirname(__FILE__)}/fixtures/**/*.rb"].each do |file|
+  require file
+end
+
+# Require library up front
+require 'braque'
+require 'shoulda/matchers'
+require 'webmock/rspec'

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: braque
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dylan Fareed
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hyperclient
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: active_attr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+description: Braque provides a simple interface for interacting with Hypermedia API
+  services in Ruby apps.
+email:
+- email@dylanfareed.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/braque.rb
+- lib/braque/collection.rb
+- lib/braque/model.rb
+- lib/braque/version.rb
+- spec/braque/collection_spec.rb
+- spec/braque/model_spec.rb
+- spec/fixtures/collection.json
+- spec/fixtures/resource.json
+- spec/fixtures/root.json
+- spec/spec_helper.rb
+homepage: https://github.com/dylanfareed/braque
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: Braque provides a simple interface for interacting with Hypermedia API services
+  in Ruby apps.
+test_files: []