zootool 0.1.0

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Ryan Mauer
+
+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.rdoc

@@ -0,0 +1,86 @@
+= zootool
+
+Provides a ruby wrapper around the Zootool API http://zootool.com/api.
+
+Zootool is about collecting, organizing and sharing your favorite images, videos, documents and links from all over the internet. This gem gives you a simple and easy way to access everything Zootool from your ruby projects. You can see it in action in the wild at http://ryanmauer.com.
+
+== Installation
+
+  $ gem install zootool
+  
+== Usage
+
+Using this gem is simple. You simply create a ZooApi object:
+
+  require 'zootool'
+
+  # You'll access everything through a ZooApi object
+  zoo = Zootool::ZooApi.new('your_api_key_here')
+
+And use its users, item, and items methods to access data from Zootool:
+
+  # Get items for a specific user. Returns an array of hashes with each hash representing an item.
+  my_items = zoo.users('rmauer').items
+  
+  # Get items for all users. Returns an array of hashes.
+  all_items = zoo.users.items
+  
+  # Get a single item by its uid. This returns a single hash.
+  an_item = zoo.item('1kf7s')
+  
+  # Gets the most popular items today.
+  popular_today = zoo.items.popular('today')
+  
+Each of these methods returns either an array of hashes or a single hash (see the method documentation for more details on what is returned and what keys the hashes contain).
+
+== More Examples
+
+If you learn by example, this should show you pretty much everything you need to know to start using this gem: 
+
+  require 'zootool'
+  
+  # You'll access everything through a ZooApi object
+  zoo = Zootool::ZooApi.new('your_api_key_here')
+  
+  # Example queries
+  my_items = zoo.users('rmauer').items
+  my_info = zoo.users('rmauer').info
+  my_friends = zoo.users('rmauer').friends
+  my_followers = zoo.users('rmauer').followers
+  my_inspiration_items = zoo.users('rmauer').items(:tag => 'inspiration')
+  all_inspiration_items = zoo.users.items(:tag => 'inspiration')
+  paged_items = zoo.users.items(:limit => 10, :offset => 20)
+  popular_today = zoo.items.popular('today')
+
+  # Using the returned data
+  first_title = popular_today[0]['title']
+  first_thumb = popular_today[0]['thumbnail']
+
+== Features
+
+* Query items by user
+* Query items for all users
+* Query popular items 
+* Query items by tag
+* Perform paging of items using limit and offset parameters
+* Access user info, friends, followers, and profiles
+
+== Planned Features
+
+* Authentication to allow access to private items
+
+== Contributing to zootool
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Ryan Mauer. See LICENSE.txt for
+further details.
+

data/lib/zootool.rb

@@ -0,0 +1,9 @@
+module Zootool
+  # The base url of the Zootool API.
+  API_URL = "http://zootool.com/api/".freeze
+end
+
+require File.dirname(__FILE__) + '/zootool/zoo_query'
+require File.dirname(__FILE__) + '/zootool/users_query'
+require File.dirname(__FILE__) + '/zootool/items_query'
+require File.dirname(__FILE__) + '/zootool/zootool_api'

data/lib/zootool/items_query.rb

@@ -0,0 +1,39 @@
+require 'zootool/zoo_query'
+
+module Zootool
+  
+  # Performs Zootool item queries to the Zootool API. This includes queries
+  # for popular items.
+  #
+  # Usage: You don't need to create an object of this class directly. Instead 
+  # use the item method on your ZootoolApi object.
+  #
+  # See http://zootool.com/api/docs/items for Items API documentation.
+  #
+  class ItemsQuery < ZooQuery
+
+    # Returns the info for an item with the specified uid.
+    #
+    # Returns a hash containing the item info.
+    #
+    def info(uid)
+      hash = {:uid => uid}
+      @api.request("items/info/?#{build_query_string(hash)}")
+    end
+  
+    # Returns the most popular items. The time period for which to return
+    # popular items may be specified via the type parameter. Valid values
+    # are: all, month, week, today. If not specified (or if an invalid time
+    # period is specified), it will default to all.
+    #
+    # Returns an array of hashes containing item info.
+    # 
+    def popular(type='all')
+      # ensure only allowed popular types
+      type = 'all' unless ['all','month','week','today'].include?(type)
+      @api.request("items/popular/?type=#{type}")
+    end
+  
+  end
+
+end

data/lib/zootool/users_query.rb

@@ -0,0 +1,115 @@
+require 'zootool/zoo_query'
+
+module Zootool
+  
+  # Performs User queries to the Zootool API. 
+  #
+  # Usage: You don't need to create an object of this class directly. Instead 
+  # use the users method on your ZootoolApi object.
+  #
+  # See http://zootool.com/api/docs/users for Users API documentation.
+  #
+  class UsersQuery < ZooQuery
+  
+    # The username of the user for which the API should return results.
+    attr_accessor :username
+  
+    # Initializes the UsersQuery.
+    def initialize api, username
+      @api = api
+      @username = username
+    end
+  
+    # Requests and returns the items for a specific user. Private items will be
+    # returned if authenticated. If username is nil or empty, items for all users
+    # will be returned.
+    # 
+    # Optional Supported Arguments: tag, offset, limit
+    #
+    # Returns an array of zero or more hashes where each hash contains the info
+    # for an item. The hash keys (as of the current version of the API) include:
+    #  - uid: the unique id of the item
+    #  - title: the title of the item
+    #  - url: the url of the item
+    #  - added: when the item was added
+    #  - type: the type of the item (page, etc.)
+    #  - views: the number of views for the item (a string)
+    #  - likes: the number of likes the item has received (a string)
+    #  - comments: the number of comments the item has received (a string)
+    #  - permalink: the url of the permalink for the item
+    #  - tinyurl: a tiny url for linking to the item
+    #  - thumbnail: the url of the thumbnail for the item
+    #  - image: the url of the image for the item
+    #  - referer: the page from which the item was captured
+    #  - description: a description of the item
+    #  - tags: an array of tags for the item
+    #  - inthezoo: a boolean
+    #  - public: a boolean indicating whether or not the item is public
+    #
+    def items *args
+      hash = args_to_hash(args)
+      hash[:username] = @username unless @username.nil? || @username.empty?
+      @api.request("users/items/?#{build_query_string(hash)}")
+    end
+  
+    # Returns info about a certain user. If username is nil or empty, the API
+    # will return an error.
+    #
+    # Returns a hash containing the info for a user. The hash keys (as of the
+    # current version of the API) include:
+    #  - username: the username of the user
+    #  - website: the url of the user's website
+    #  - avatar: the url of the user's avatar image
+    #  - profile: the url of the user's profile
+    #
+    def info
+      hash = {:username => @username}
+      @api.request("users/info/?#{build_query_string(hash)}")
+    end
+  
+    # Returns a list of friends for a specific user. If username is nil or empty,
+    # the API will return an error.
+    #
+    # Optional Supported Arguments: offset, limit, search
+    #
+    # Returns an array of hashes containing user info.
+    #
+    def friends *args
+      hash = args_to_hash(args)
+      hash[:username] = @username
+      @api.request("users/friends/?#{build_query_string(hash)}")
+    end
+  
+    # Returns a list of followers for a specific user. If username is nil or empty,
+    # the API will return an error.
+    #
+    # Optional Supported Arguments: offset, limit, search
+    #
+    # Returns an array of hashes containing user info.
+    #
+    def followers *args
+      hash = args_to_hash(args)
+      hash[:username] = @username
+      @api.request("users/followers/?#{build_query_string(hash)}")
+    end
+  
+    # Returns a list of external profiles for a user. If username is nil or empty,
+    # the API will return an error.
+    #
+    # Returns an array of hashes where each hash contains info for a user's profile
+    # on an external site, including the following info: slug, url, title
+    # 
+    def profiles
+      hash = {:username => @username}
+      @api.request("users/profiles/?#{build_query_string(hash)}")
+    end
+  
+    # Not implemented yet.
+    #
+    def validate
+      return nil
+    end
+  
+  end
+  
+end

data/lib/zootool/zoo_query.rb

@@ -0,0 +1,39 @@
+module Zootool
+  
+  # The base class for other Zootool API query classes. Simply provides
+  # common functionality to simplify the API querying process.
+  #
+  class ZooQuery
+  
+    # The ZootoolApi to use for making requests.
+    attr_accessor :api
+  
+    # Initializes the ZooQuery.
+    def initialize api
+      @api = api
+    end
+  
+    # Builds a query string from a hash for use in the query URL in the form: 
+    # key1=value1&key2=value2
+    #
+    def build_query_string hash=nil
+      return '' if hash.nil?
+      return (hash.to_a.map {|q| "#{q[0]}=#{q[1]}"}).join("&")
+    end
+  
+    # Returns a hash containing the first element of the specified
+    # args array or a new hash if the args array is nil or empty.
+    # This is simply a convenience to simplify the API queries that
+    # allow optional arguments.
+    #
+    def args_to_hash args
+      if args.nil? || args.length < 1
+        return {}
+      else
+        return args[0]
+      end
+    end
+  
+  end
+  
+end

data/lib/zootool/zootool_api.rb

@@ -0,0 +1,77 @@
+require 'httparty'
+require 'json'
+
+module Zootool
+  
+  # A wrapper that provides access to the Zootool API.
+  #
+  class ZootoolApi
+    
+    # HTTP requests are made via HTTParty
+    include HTTParty
+    
+    # The API key for your Zootool application. Set when creating a new ZootoolApi.
+    attr_accessor :api_key
+    
+    # Initializes the ZootoolApi object for making requests. You must specify your
+    # Zootool Application API key for requests to return data successfully.
+    #
+    # Example:
+    #
+    #   api = Zootool::ZootoolApi.new('your_api_key_goes_here')
+    # 
+    def initialize api_key
+      @api_key = api_key
+    end
+    
+    # Provides a simple way to get Zootool items and info for users.
+    #
+    # Returns a UsersQuery that provides methods to easily access the items and
+    # other info for users. The methods of the returned UsersQuery return a
+    # 
+    # Example:
+    #
+    #   api = Zootool::ZootoolApi.new('your_api_key')
+    #   user_items = api.users('rmauer').items
+    #   all_items = api.users.items
+    #   all_paged = api.users.items(:limit => 5, :offset => 10)
+    #
+    def users username=nil
+      Zootool::UsersQuery.new(self,username)
+    end
+    
+    # Provides a simple way to get a specific item by its uid. This is just
+    # shorthand for the longer api.items.info method.
+    #
+    # Example: 
+    #
+    #   api = Zootool::ZootoolApi.new('apikey')
+    #   item_by_uid = api.item('1kf7s')
+    #
+    def item uid
+      self.items.info(uid)
+    end
+    
+    # Provides a simple way to get items.
+    #
+    # Example:
+    #
+    #   api = Zootool::ZootoolApi.new('apikey')
+    #   items = api.items.popular('week')
+    #   item_by_uid = api.items.info('1kf7s')
+    #
+    def items
+      Zootool::ItemsQuery.new(self)
+    end
+    
+    # Makes a request to the specified path and returns a Hash containing
+    # the result of the HTTP request.
+    #
+    def request(path)
+      url = "#{Zootool::API_URL}#{path}&apikey=#{@api_key}"
+      self.class.get(url).parsed_response
+    end
+    
+  end
+  
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification 
+name: zootool
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Ryan Mauer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-09 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.6.2
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+description: A ruby wrapper for the Zootool API. See http://zootool.com/api for the official API documentation.
+email: me@ryanmauer.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- lib/zootool.rb
+- lib/zootool/items_query.rb
+- lib/zootool/users_query.rb
+- lib/zootool/zoo_query.rb
+- lib/zootool/zootool_api.rb
+- LICENSE.txt
+- README.rdoc
+homepage: http://github.com/ryanmauer/zootool
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 984848100567268235
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper for the Zootool API
+test_files: []
+