braque 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d74d0cde5c073286613ad279b4221f967934c72
-  data.tar.gz: a296e958733e8c9036709d63085dc0950b113ec8
+  metadata.gz: d7a9f3bb1b0fa79bccb708a0bf57e0b6a52f9e2b
+  data.tar.gz: 1e41b55a3b55791b8e5b66aacdffadddee401427
 SHA512:
-  metadata.gz: 9a2b799f95dbd2f03e2e01e4cd8d2ee0f7332edadc5988b512e01e352f6819a0f6ebb05cda6fb214f8638894df84d98b16f2b951c4e4ad20f040a80fc5788187
-  data.tar.gz: 2accbbe9c093abff560a73b6c596eb9890910b90cda5c1b2f84f75e7246cc3d9c4257b52d1cb9b047e5e1609ed5f2d321c5029ecaf48e631b94fe9c2f250ed18
+  metadata.gz: 69f0e4507806a662441bbde237a173b17bd5d4067ef31d11208aa40f77efb437e0578e6f48d7c22af29849dac032760da27bafc45b50d5b97747268a067e9336
+  data.tar.gz: b0c7e6a4e5a7dd55ce7d39f48227edf1efd1280ff7e0579ea47230cabd099a4288f3b06adbe9e356428ba70b49ef9feb8fd5b8efa20e1a851449a985555f388b

data/README.md

@@ -2,13 +2,13 @@
 
 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. That said, at [Artsy](https://www.artsy.net), we've used Braque to consume [Gris](https://github.com/artsy/gris) APIs with great benefit.
+Braque is an early-stage and exploratory project. That said, at [Artsy](https://www.artsy.net), we've used Braque to quickly consume [Gris](https://github.com/artsy/gris) Hypermedia APIs with great benefit.
 
 [![Build Status](https://semaphoreci.com/api/v1/projects/c557a59e-1c1a-4719-a41a-6462a424ddfa/381676/badge.png)](https://semaphoreci.com/dylanfareed/braque)
 
-### Model setup
+### Basic 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 listing attributes which we expect to receive from the API.
+```Braque::Model``` is an 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 (required), and listing attributes which we expect to receive from the API.
 
 ```ruby
 class Article
@@ -24,34 +24,94 @@ class Article
 end
 ```
 
-### Credentials
+Braque::Model adds familiar "Active Record"-like `create`, `find`, and `list` class methods to the embedding class (`Article` in the example above) as well as `save` and `destroy` instance methods. These methods wrap Hyperclient to make calls to a remote hypermedia API.
 
-```Braque::Model``` also supports multiple API authentication strategies. Defining `http_authorization_header` or `accept_header` with the model will pass those credentials to the provider API with each request.
+### Relations
 
-For example, `http_authorization_header` credentials defined here are added to the request's `Http-Authorization` headers.
+If your remote API includes associated resources in the `_links` node for a given resource, you can use Braque's relations helpers to make navigating to those associated resources somewhat simpler.
 
-```ruby
-class Article
-  include Braque::Model
-  api_root_url Rails.application.config_for(:articles_service)['url']
-  http_authorization_header Rails.application.config_for(:articles_service)['token']
+For example if the remote API returns a response for the Book resource like this:
 
+```
+{
+  "id":1,
+  "title":"My Magazine",
+  "_links":{
+    "self":{
+      "href":"http://localhost:9292/magazines/1"
+    },
+    "articles":{
+      "href":"http://localhost:9292/articles?magazine_id=1{&page,size}",
+      "templated":true
+    }
+  }
+}
+```
+
+And the remote API returns something like the following for a give Article resource:
+
+```
+{
+  "id":1,
+  "title":"My Article",
+  "magazine_id": 1,
+  "content":"Lorem ipsum...",
+  "_links":{
+    "self":{
+      "href":"http://localhost:9292/articles/1"
+    },
+    "magazine":{
+      "href":"http://localhost:9292/magazines/1"
+    }
+  }
+}
+```
+
+In this situation you could choose to setup your Magazine and Article models to include `has_many` and `belongs_to` association helpers.
+
+```ruby
+class Magazine
+  include ::Braque::Model
+  api_root_url 'http://localhost:9292'
+  has_many :articles
   attribute :id
   attribute :title
 end
+
+class Article
+  include ::Braque::Model
+  api_root_url 'http://localhost:9292'
+  belongs_to :magazine
+  attribute :id
+  attribute :content
+  attribute :magazine_id
+end
+```
+
+This will allow you to retrieve associated resources without manually constructing a new link.
+
+So instead of something like
+
+```ruby
+magazine = Magazine.find id: article.magazine_id
 ```
 
-Defining an `accept_header` credential will replace Hyperclient's default `Accept` header with the value you provide.
+you may use the `belongs_to` helper to retrieve the associated resource more simply with
 
 ```ruby
-class Article
-  include Braque::Model
-  api_root_url Rails.application.config_for(:articles_service)['url']
-  accept_header Rails.application.config_for(:articles_service)['accept_header']
+magazine = article.magazine
+```
 
-  attribute :id
-  attribute :title
-end
+Similarly, the `has_many` helper provides retrieval methods for accessing associated resources.
+
+```ruby
+articles = magazine.articles
+```
+
+This method supports passing params to the remote API as well.
+
+```ruby
+articles = magazine.articles(page: 2, size: 20)
 ```
 
 ### Controllers
@@ -98,3 +158,57 @@ class ArticlesController < ApplicationController
 end
 
 ```
+
+### Subclassing
+
+Braque supports inheritance for shared setup across multiple models in your app that make calls to the same remote API.
+
+In the following example, `Article` and `Author` classes will inherit the `api_root_url` and `id`, `created_at`, and `updated_at` attributes from `RemoteModel`.
+
+```ruby
+class RemoteModel
+  include Braque::Model
+  api_root_url Rails.application.config_for(:remote_service)['url']
+
+  attribute :id
+  attribute :created_at
+  attribute :updated_at
+end
+```
+
+```ruby
+class Article < RemoteModel
+  attribute :title
+  attribute :body
+  attribute :summary
+end
+```
+
+```ruby
+class Author < RemoteModel
+  attribute :first_name
+  attribute :last_name
+end
+```
+
+### Custom Headers
+
+Braque also supports passing additional headers along with API requests to your remote provider API service.
+
+* Defining an `accept_header` will replace Hyperclient's default `Accept` header with the value you provide.
+* Defining an `authorization_header` with your model will result in this value being sent over in an `Authorization` header with your requests.
+* Defining an `http_authorization_header` with your model will result in this value being sent over in an `Http-Authorization` header with your requests.
+
+To wit:
+
+```ruby
+class Article
+  include Braque::Model
+  api_root_url Rails.application.config_for(:articles_service)['url']
+  http_authorization_header Rails.application.config_for(:articles_service)['token']
+  accept_header Rails.application.config_for(:articles_service)['accept_header']
+
+  attribute :id
+  attribute :title
+end
+```

data/lib/braque/model.rb

@@ -72,6 +72,7 @@ module Braque
 
     module ClassMethods
       include Braque::Collection
+      include Braque::Relations
 
       [:api_root_url, :accept_header, :authorization_header, :http_authorization_header].each do |config_option|
         define_method config_option do |value|

data/lib/braque/relations.rb

@@ -0,0 +1,27 @@
+module Braque
+  module Relations
+    def belongs_to(relation)
+      define_method relation do
+        relation.to_s.classify.constantize.new(
+          self.class.client.method(self.class.instance_method_name)
+            .call(resource_find_options)
+            .method(relation).call
+        )
+      end
+    end
+
+    # rubocop:disable Style/PredicateName
+    def has_many(relation)
+      define_method relation do |params = {}|
+        response = self.class.client.method(self.class.instance_method_name)
+                   .call(resource_find_options)
+                   .method(relation).call(params)
+        Braque::Collection::LinkedArray.new(
+          response,
+          relation.to_s.classify.singularize.constantize
+        )
+      end
+    end
+    # rubocop:enable Style/PredicateName
+  end
+end

data/lib/braque/version.rb

@@ -1,3 +1,3 @@
 module Braque
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/braque.rb

@@ -3,6 +3,7 @@ require 'active_attr'
 require 'hyperclient'
 require 'braque/version'
 require 'braque/collection'
+require 'braque/relations'
 require 'braque/model'
 
 module Braque

data/spec/braque/relations_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+RSpec.describe Braque::Relations, type: :model do
+  context 'with multiple defined Braque::Model classes' do
+    before do
+      class Breeze
+        include ::Braque::Model
+        api_root_url 'http://localhost:9292'
+        has_many :tides
+        attribute :id
+        attribute :title
+      end
+
+      class Tide
+        include ::Braque::Model
+        api_root_url 'http://localhost:9292'
+        belongs_to :breeze
+        attribute :id
+        attribute :title
+      end
+    end
+
+    let(:root_response) { JSON.parse(File.read 'spec/fixtures/root.json') }
+    let(:breeze_response) { JSON.parse(File.read 'spec/fixtures/resource.json') }
+    let(:tide_response) { JSON.parse(File.read 'spec/fixtures/associated_resource.json') }
+    let(:tides_response) { JSON.parse(File.read 'spec/fixtures/associated_collection.json') }
+
+    let(:root_request) do
+      WebMock.stub_request(:get, "#{Breeze.config[:api_root_url]}/")
+        .to_return(status: 200, body: root_response)
+    end
+
+    let(:breeze_request) do
+      WebMock.stub_request(:get, "#{Breeze.config[:api_root_url]}/breezes/1")
+        .to_return(status: 200, body: breeze_response)
+    end
+
+    let(:tide_request) do
+      WebMock.stub_request(:get, "#{Tide.config[:api_root_url]}/tides/1")
+        .to_return(status: 200, body: tide_response)
+    end
+
+    let(:tides_request) do
+      WebMock.stub_request(:get, "#{Tide.config[:api_root_url]}/tides?account_id=1")
+        .to_return(status: 200, body: tides_response)
+    end
+
+    let(:breeze) { Breeze.new id: 1 }
+    let(:tide) { Tide.new id: 1 }
+
+    before do
+      root_request
+      breeze_request
+      tide_request
+      tides_request
+    end
+
+    context 'has_many' do
+      it 'defines a dynamic instance method for association' do
+        expect(breeze.methods).to include :tides
+      end
+
+      it 'returns an array of associated objects' do
+        associated = breeze.tides
+        expect(associated.total_count).to eq 2
+      end
+
+      it 'returns an array of associated objects' do
+        associated = breeze.tides.first
+        expect(associated.class).to eq Tide
+        expect(associated.title).to eq(
+          tides_response['_embedded']['tides'].first['title']
+        )
+      end
+    end
+
+    context 'belongs_to' do
+      it 'defines a dynamic instance method for association' do
+        expect(tide.methods).to include :breeze
+      end
+
+      it 'returns the correct associated object' do
+        associated = tide.breeze
+        expect(associated.class).to eq Breeze
+        expect(associated.title).to eq breeze_response['title']
+      end
+    end
+  end
+end

data/spec/fixtures/associated_collection.json

@@ -0,0 +1,32 @@
+{
+   "total_count":2,
+   "total_pages":1,
+   "current_page":1,
+   "_links":{
+      "self":{
+         "href":"http://localhost:9292/tides"
+      }
+   },
+   "_embedded":{
+      "tides":[
+         {
+            "id":0,
+            "title":"Southerly Tides",
+            "_links":{
+               "self":{
+                  "href":"http://localhost:9292/tides/0"
+               }
+            }
+         },
+         {
+            "id":1,
+            "title":"Westerly Tides",
+            "_links":{
+               "self":{
+                  "href":"http://localhost:9292/tides/1"
+               }
+            }
+         }
+      ]
+   }
+}

data/spec/fixtures/associated_resource.json

@@ -0,0 +1,14 @@
+{
+  "id":1,
+  "title":"Some tide",
+  "created_at":"2015-02-11T18:59:01.669Z",
+  "updated_at":"2015-02-12T00:26:22.255Z",
+  "_links":{
+    "self":{
+      "href":"http://localhost:9292/tides/1"
+    },
+    "breeze":{
+      "href":"http://localhost:9292/breezes/1"
+    }
+  }
+}

data/spec/fixtures/resource.json

@@ -1,12 +1,16 @@
 {
-   "id":1,
-   "token":123,
-   "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"
-      }
-   }
+  "id":1,
+  "token":123,
+  "title":"Southerly Breeze",
+  "created_at":"2015-02-11T18:59:01.669Z",
+  "updated_at":"2015-02-12T00:26:22.255Z",
+  "_links":{
+    "self":{
+      "href":"http://localhost:9292/breezes/1"
+    },
+    "tides":{
+      "href":"http://localhost:9292/tides?account_id=1{&page,size}",
+      "templated":true
+    }
+  }
 }

data/spec/fixtures/root.json

@@ -13,6 +13,14 @@
       "breeze":{
          "href":"http://localhost:9292/breezes/{id}",
          "templated":true
+      },
+      "tides":{
+         "href":"http://localhost:9292/tides{?page,size}",
+         "templated":true
+      },
+      "tide":{
+         "href":"http://localhost:9292/tides/{id}",
+         "templated":true
       }
    }
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: braque
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dylan Fareed
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-10 00:00:00.000000000 Z
+date: 2015-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hyperclient
@@ -65,6 +65,7 @@ files:
 - lib/braque.rb
 - lib/braque/collection.rb
 - lib/braque/model.rb
+- lib/braque/relations.rb
 - lib/braque/version.rb
 - spec/braque/api_root_spec.rb
 - spec/braque/client_headers_spec.rb
@@ -72,7 +73,10 @@ files:
 - spec/braque/model_attributes_spec.rb
 - spec/braque/model_spec.rb
 - spec/braque/multiple_model_spec.rb
+- spec/braque/relations_spec.rb
 - spec/braque/subclassed_model_spec.rb
+- spec/fixtures/associated_collection.json
+- spec/fixtures/associated_resource.json
 - spec/fixtures/collection.json
 - spec/fixtures/resource.json
 - spec/fixtures/root.json