siren_client 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8341e11f509b82395f8ae9c653301abeadc3b6a
+  data.tar.gz: fd41f07b2c546db3cb64047d83fc23cc88be7d2c
+SHA512:
+  metadata.gz: 8122952b651d378955248c0d3bb94df1f6d9965e2aec1e3d0ecfcc91a6104ba209d14bd67734ac944e6e7d302ed174b925c5e45724b75a661a4031c122699a6f
+  data.tar.gz: 0eb6e64977eb00c6710f1e5fbfcc964d9e5ecb341c63ff534b536175e5d46b5ad5d39944f65c6f79e99a55f365c7cc37b63f530e8dba126419cdc7935de6caaa

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in siren_client.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,11 @@
+guard 'rspec', cmd: "bundle exec rspec" do
+  # watch /lib/ files
+  watch(%r{^lib/siren_client/(.+).rb$}) do |m|
+    "spec/unit/#{m[1]}_spec.rb"
+  end
+
+  # watch /spec/ files
+  watch(%r{^spec/(.+)/(.+).rb$}) do |m|
+    "spec/#{m[1]}/#{m[2]}.rb"
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Chason Choate
+
+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

@@ -0,0 +1,103 @@
+# SirenClient
+
+A simple client for traversing Siren APIs. Not sure what Siren is? View the spec here: https://github.com/kevinswiber/siren.
+
+## Usage
+
+Grabbing the root of the API.
+
+```ruby
+require 'siren_client'
+
+# The simplest form
+root = SirenClient.get('http://siren-api.example.com')
+
+# Advanced usage
+root = SirenClient.get('http://siren-api.example.com', {
+  headers: { "Accept": "application/json", ... },
+  basic_auth: { username: 'person', password: '1234' },
+  timeout: 5,
+  ... # Refer to https://github.com/jnunemaker/httparty/blob/master/lib/httparty.rb#L45
+      # For more options.
+})
+```
+
+There are four main parts to an [Entity](https://github.com/kevinswiber/siren#entity) in Siren. (properties, entities, links, and actions) To make your life a little easier SirenClient will try to pick one of the four items given a method name. Otherwise you can access the data directly.
+
+### Properties
+
+```ruby
+# If color was a property on the root you could do something like this:
+root.color 
+# or 
+root.properties['color']
+```
+
+### Entities
+
+Since entities are usually the most important, SirenClient provides enumerable support to obtain them.
+
+```ruby
+# Will grab the entity as if root was an array.
+root[x] 
+# or
+root.entities[x] # This is an array
+# Will iterate through all the entities on the root.
+root.each do |entity|
+  # do something
+end
+```
+
+#### Entity sub-links
+
+If the root contains an entity that is an [embedded link](https://github.com/kevinswiber/siren#embedded-link) you can call it based on it's class name. This will also execute the link's href and return you the entity.
+
+```ruby
+root.embedded_link_class_name
+root.messages # For example
+```
+
+### Links
+
+```ruby
+# If you know the link's name you could do something like this:
+root.concepts
+# or
+root.links['concepts'].go
+```
+
+### Actions
+
+```ruby
+# Again, if you know the action's name you can do this:
+root.filter_concepts.where(name: 'github', status: 'active')
+# or
+root.actions['filter_concepts'].where(...)
+```
+
+#### Fields
+
+Actions have fields that are used to make the request when you use `.where`. To see those fields you can do this:
+
+```ruby
+action = root.actions[0]
+action.fields.each do |field|
+  puts "#Field: {field.name}, #{field.type}, #{field.value}, #{field.title}"
+end
+```
+
+## Development
+
+Run the following commands to start development:
+
+```bash
+bundle install
+bundle exec guard 
+# This will open a CLI that watches files for changes.
+```
+
+I've included `byebug` as a development dependency and you may use it as well.
+
+## Thanks To
+
+Kevin Swiber - For creating the Siren spec and giving this project meaning.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec, :tag) do |t, task_args|
+    t.rspec_opts = '--color'
+  end
+rescue LoadError
+  # no rspec available
+end

data/bin/siren_cli

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'byebug'
+require 'siren_cli'
+
+SirenCLI::Shell.new

data/lib/siren_cli.rb

@@ -0,0 +1,9 @@
+require "siren_cli/version"
+
+# Dependencies
+require 'json'
+require 'readline'
+require 'siren_client'
+
+# SirenClient files
+require 'siren_cli/shell'

data/lib/siren_cli/shell.rb

@@ -0,0 +1,85 @@
+module SirenCLI
+    class Shell
+        def initialize
+            root = get_root
+            @ent_stack = []
+            @ent = root
+            display_entity
+            loop_input
+        end
+        def loop_input
+            while input = Readline.readline('(ent)> ', true).chomp
+                exit if ['exit', 'quit'].include?(input.downcase)
+                case input.downcase
+                when 'b', 'back'
+                    if @ent_stack.length == 0
+                        puts "Already at the root entity."
+                        next
+                    end
+                    @ent = @ent_stack.pop 
+                    display_entity
+                    next
+                when 's', 'summary'
+                    display_entity
+                    next
+                end
+                begin
+                    ent = @ent
+                    val = eval input
+                    if val.is_a? SirenClient::Entity
+                        @ent_stack << @ent
+                        @ent = val
+                        display_entity
+                    else
+                        puts val unless input.empty?
+                    end
+                rescue SyntaxError => e
+                    puts "#{e.class} - #{e.message}"
+                rescue StandardError => e
+                    puts "#{e.class} - #{e.message}"
+                end
+            end
+        end
+        
+        def get_root
+            @root_url = Readline.readline('Root URL> ', true).chomp
+            SirenClient.get(@root_url)
+        end
+
+        def display_entity
+            puts "----------------------------------"
+            puts "  Entity: #{get_href(@ent.links['self'] && @ent.links['self'].href)}"
+            puts "----------------------------------"
+            puts "  Properties: #{@ent.properties.keys.length}"
+            @ent.properties.each do |k, v|
+                val = v.to_s
+                ind = @ent.properties.keys[-1] == k ? '└──' : '├──'
+                puts "    #{ind} #{k}: #{val.length > 80 ? val[0..80] + '...' : val}"
+            end
+            puts "  Entities: #{@ent.entities.length}"
+            @ent.entities.each_with_index do |e, i|
+                ind = @ent.entities[-1] == e ? '└──' : '├──'
+                is_collection = e.classes.include?('collection')
+                puts "    #{ind} [#{i}] #{e.properties.to_s.length > 80 ? e.properties.to_s[0..80] + '...' : e.properties}" unless is_collection
+                puts "    #{ind} [#{i}] #{e.rels[0]}: #{get_href(e.href)}" if is_collection
+            end
+            puts "  Links: #{@ent.links.length}"
+            @ent.links.each do |k, link|
+                ind = @ent.links.keys[-1] == k ? '└──' : '├──'
+                puts "    #{ind} #{link.rels[0]}: #{get_href(link.href)}"
+            end
+            puts "  Actions: #{@ent.actions.length}"
+            @ent.actions.each do |k, action|
+                ind = @ent.actions.keys[-1] == k ? '└──' : '├──'
+                puts "    #{ind} #{action.name}: #{action.method.upcase} #{action.fields.map { |f| f.name + '[' + f.type + ']' }.join(', ')}"
+            end
+        end
+
+        def get_href(href)
+            return 'Unknown' unless href
+            return href unless @root_url
+            trimmed = href.gsub(@root_url, '')
+            trimmed.empty? ? '/' : trimmed
+        end
+    end
+end

data/lib/siren_cli/version.rb

@@ -0,0 +1,3 @@
+module SirenCLI
+  VERSION = "0.0.1"
+end

data/lib/siren_client.rb

@@ -0,0 +1,17 @@
+dir = 'siren_client'
+require "#{dir}/version"
+
+# Dependencies
+require 'json'
+require 'logger'
+require 'httparty'
+require 'active_support/inflector'
+require 'active_support/core_ext/hash'
+
+# SirenClient files
+require "#{dir}/exceptions"
+require "#{dir}/link"
+require "#{dir}/field"
+require "#{dir}/action"
+require "#{dir}/entity"
+require "#{dir}/base"

data/lib/siren_client/action.rb

@@ -0,0 +1,47 @@
+module SirenClient
+  class Action
+    attr_reader :payload, :name, :classes, :method, :href, :title, :type, :fields, :config
+
+    def initialize(data, config={})
+      if data.class != Hash
+        raise ArgumentError, "You must pass in a Hash to SirenClient::Action.new"
+      end
+      @payload = data
+
+      @config = { format: :json }.merge config 
+      @name    = @payload['name']   || ''
+      @classes = @payload['class']  || []
+      @method  = (@payload['method'] || 'GET').downcase
+      @href    = @payload['href']   || ''
+      @title   = @payload['title']  || ''
+      @type    = @payload['type']   || 'application/x-www-form-urlencoded'
+      @fields  = @payload['fields'] || []
+      @fields.map! do |data|
+        SirenClient::Field.new(data)
+      end
+    end
+
+    def where(params = {})
+      options = { headers: {}, query: {}, body: {} }.merge @config
+      if @method == 'get'
+        options[:query] = params
+      else
+        options[:body] = params
+      end
+      options[:headers]['Content-Type'] = @type
+      begin
+        query = options[:query].empty? ? '' : ('?' + options[:query].to_query)
+        SirenClient.logger.debug "#{@method.upcase} #{@href}#{query}"
+        options[:headers].each do |k, v|
+          SirenClient.logger.debug "  #{k}: #{v}"
+        end
+        SirenClient.logger.debug '  ' + options[:body].to_query unless options[:body].empty?
+        Entity.new(HTTParty.send(@method.to_sym, @href, options).parsed_response, @config)
+      rescue URI::InvalidURIError => e
+        raise InvalidURIError, e.message
+      rescue JSON::ParserError => e
+        raise InvalidResponseError, e.message
+      end
+    end
+  end
+end

data/lib/siren_client/base.rb

@@ -0,0 +1,32 @@
+module SirenClient
+  # Add a logger that gets passed in from an outside source
+  # or default to a standard logger. This will allow different
+  # setups i.e. java logging to log wherever/however they wish.
+  @@logger = Logger.new(STDOUT)
+  @@logger.level = Logger::WARN
+  @@logger.progname = 'SirenClient.' + SirenClient::VERSION
+  def self.logger; @@logger; end
+  def self.logger=(log)
+    unless  log.respond_to?(:debug) &&
+            log.respond_to?(:info)  &&
+            log.respond_to?(:warn)  &&
+            log.respond_to?(:error) &&
+            log.respond_to?(:fatal)
+      raise InvalidLogger, "The logger object does not respond to [:debug, :info, :warn, :error, :fatal]."
+    end
+    @@logger = log
+    @@logger.progname = 'SirenClient.' + SirenClient::VERSION
+  end
+
+  def self.get(options)
+    if options.is_a? String
+      Entity.new(options)
+    elsif options.is_a? Hash
+      url = options[:url] || options['url']
+      raise ArgumentError, "You must supply a valid url to SirenClient.get" unless url
+      Entity.new(url, options)    
+    else
+      raise ArgumentError, 'You must supply either a string or hash to SirenClient.get'
+    end
+  end
+end

data/lib/siren_client/entity.rb

@@ -0,0 +1,112 @@
+module SirenClient
+  class Entity
+    attr_reader :payload, :classes, :properties, :entities, :rels, 
+                :links, :actions, :title, :type, :config, :href
+
+
+    def initialize(data, config={})
+      @config = { format: :json }.merge config 
+      if data.class == String
+        unless data.class == String && data.length > 0
+            raise InvalidURIError, 'An invalid url was passed to SirenClient::Entity.new.'
+        end
+        begin
+          SirenClient.logger.debug "GET #{data}"
+          @payload = HTTParty.get(data, @config).parsed_response
+        rescue URI::InvalidURIError => e
+          raise InvalidURIError, e.message
+        rescue JSON::ParserError => e
+          raise InvalidResponseError, e.message
+        end
+      elsif data.class == Hash
+          @payload = data
+      else
+          raise ArgumentError, "You must pass in either a url(String) or an entity(Hash) to SirenClient::Entity.new"
+      end
+      parse_data
+    end
+
+    # Execute an entity sub-link if called directly
+    # otherwise just return the entity.
+    def [](i)
+      @entities[i].href.empty? ? @entities[i] : @entities[i].go rescue nil
+    end
+
+    def each(&block)
+      @entities.each(&block) rescue nil
+    end
+
+    ### Entity sub-links only
+    def go
+      return if self.href.empty?
+      self.class.new(self.href, @config)
+    end
+    
+    def method_missing(method, *args)
+      method_str = method.to_s
+      return @entities.length if method_str == 'length'
+      # Does it match a property, if so return the property value.
+      @properties.each do |key, prop|
+        return prop if method_str == key
+      end
+      # Does it match an entity sub-link's class? 
+      @entities.each do |ent|
+        return ent.go if ent.href && ent.classes.include?(method_str)
+      end
+      # Does it match a link, if so traverse it and return the entity.
+      @links.each do |key, link|
+        return link.go if method_str == key
+      end
+      # Does it match an action, if so return the action.
+      @actions.each do |key, action|
+        return action if method_str == key
+      end
+      raise NoMethodError, 'The method does not match a property, action, or link on SirenClient::Entity.'
+    end
+
+    private
+
+    def parse_data
+      return if @payload.nil?
+      @classes    = @payload['class']      || []
+      @properties = @payload['properties'] || { }
+      @entities   = @payload['entities']   || []
+      @entities.map! do |data|
+        self.class.new(data, @config)
+      end
+      @rels  = @payload['rel']   || []
+      @links = @payload['links'] || []
+      @links.map! do |data|
+        Link.new(data, @config)
+      end
+      # Convert links into a hash
+      @links = @links.inject({}) do |hash, link|
+        next unless link.rels.length > 0
+        # Don't use a rel name if it's generic like 'collection'
+        hash_rel = nil
+        generic_rels = ['collection']
+        link.rels.each do |rel|
+          next if generic_rels.include?(rel)
+          hash_rel = rel and break
+        end
+        # Ensure the rel name is a valid hash key
+        hash[hash_rel.underscore] = link
+        hash
+      end
+      @actions = @payload['actions'] || []
+      @actions.map! do |data|
+        Action.new(data, @config)
+      end
+      # Convert actions into a hash
+      @actions = @actions.inject({}) do |hash, action|
+        next unless action.name
+        hash[action.name.underscore] = action
+        hash
+      end
+      @title = @payload['title'] || ''
+      @type  = @payload['type']  || ''
+      # Should only be present for entity sub-links.
+      @href  = @payload['href']  || ''
+    end
+  end
+end