Permalink
Browse files

The project is now 100% documented with YARD.

  • Loading branch information...
1 parent 7039ff7 commit 325da8d4605ef7b26b372c719e5f5011e5c5995a @brianmichel brianmichel committed Apr 24, 2011
Showing with 123 additions and 4 deletions.
  1. +21 −0 lib/crate_api.rb
  2. +36 −1 lib/crate_api/base.rb
  3. +14 −0 lib/crate_api/crate.rb
  4. +17 −2 lib/crate_api/crateobject.rb
  5. +18 −0 lib/crate_api/crates.rb
  6. +11 −0 lib/crate_api/item.rb
  7. +6 −1 lib/crate_api/items.rb
View
@@ -5,7 +5,28 @@
require File.join(File.dirname(__FILE__), "crate_api", inc)
end
+# The CrateAPI Gem is a lightweight Ruby interface to the Crate file-sharing site.
+# @author Brian Michel
+# A few examples will follow in order to get everyone up to speed.
+#
+# @example Create a new Crate client.
+# client = CrateAPI.new("username", "password")
+#
+# @example Retreive all crates for a user.
+# crates = client.crates.all
+#
+# @example Create a new crate.
+# client.crate.add("YourNewAwesomeCrateName")
+#
+# @example Upload a new file to a crate.
+# crates[0].add_file("/Path/to/your/file")
+#
module CrateAPI
+ # Default initializer for a new CrateAPI instace
+ #
+ # @param [String] Username for the client.
+ # @param [String] password Password for the client.
+ # @return [CrateAPI::Base] newly initialized CrateAPI::Base instace.
def self.new(username, password)
CrateAPI::Base.new(username, password)
end
View
@@ -1,25 +1,55 @@
module CrateAPI
+ # NotValidUserError class which is raised due to bad credentials.
class NotValidUserError < Exception
+
end
-
+
+ # Base class which is used to authenticate user and perform calls.
+ #
class Base
include HTTMultiParty
+ # @attr [Hash] :auth auth hash.
attr_accessor :auth
+ # Current API Version.
API_VERSION = 1
+ # Base URL Endpoint
BASE_URL = "https://api.letscrate.com/#{API_VERSION}"
+ # Authorization URL Endpoint.
AUTH_URL = "#{BASE_URL}/users/authenticate.json"
+ # Items URL Endpoint.
ITEMS_URL = "#{BASE_URL}/files"
+ # Crates URL Endpoint.
CRATES_URL = "#{BASE_URL}/crates"
+ # Short URL Placeholder String.
SHORT_URL = "http://lts.cr/%s"
+
+ # Default initializer for getting a Crates instance.
+ # @return [CrateAPI::Crates] a new Crates instance.
def crates(); @crates || CrateAPI::Crates.new(); end
+
+ # Default initializer for getting a Items instance.
+ # @return [CrateAPI::Items] a new Items instance.
def items(); @items || CrateAPI::Items.new(); end
+ # Default initializer for the CrateAPI Client
+ #
+ # @param [String] username username for the Crate user.
+ # @param [String] password password for the Crate user.
+ # @return [CrateAPI::Base] this will return the base class instance.
+ # @raise [NotValidUserError] this will occur if the username/password pair is not valid.
def initialize(username, password)
raise NotValidUserError unless CrateAPI::Base.authorized?(username, password)
@@auth = {:username => username, :password => password}
end
+
+ # Class method that return the response body of the call.
+ #
+ # @param [String] url URL endpoint to make the call to.
+ # @param [Symbol] verb HTTP verb used for call.
+ # @param [Optional] params Hash of params used for call.
+ # @return [Object] body object from the response.
def self.call(url, verb, params={})
params.merge!({:basic_auth => @@auth})
resp = nil
@@ -34,6 +64,11 @@ def self.call(url, verb, params={})
end
end
+ # Class method that will return a boolean whether or not the user is authorized.
+ #
+ # @param [String] username Username to test for authorization.
+ # @param [String] pass Password to test for authorization.
+ # @return [Boolean] whether or not the user is authorized.
def self.authorized?(user, pass)
resp = self.get("#{AUTH_URL}", {:basic_auth => {:username => user, :password => pass}})
if resp.code == 401
@@ -1,30 +1,44 @@
module CrateAPI
+ # CrateRenameError class which is raised when there is a problem renaming a given Crate.
class CrateRenameError < Exception
end
+ # CrateDestroyError class which is raised when there is a problem destroying a given Crate.
class CrateDestroyError < Exception
end
+ # CrateFileAlreadyExistsError class which is raised when there is a problem uploading a file to a given Crate.
class CrateFileAlreadyExistsError < Exception
end
+ # Crate object class which is used to manipulate the single Crate object.
class Crate < CrateObject
attr_reader :files
def initialize(hash)
super(hash)
@files = CrateAPI::Items.from_array(hash["files"])
end
+ # Destroys the given crate object.
+ #
+ # @return [CrateDestroyError, nil] if there is an issue destroying the crate, an error will be raised with the message explaining why.
def destroy
response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CrateAPI::Crates::CRATE_ACTIONS[:destroy] % ["#{self.id}"]}", :post))
raise CrateDestroyError, response["message"] unless response["status"] != "failure"
end
+ # Renamed the given crate object.
+ #
+ # @return [CrateRenameError, nil] if there is an issue with renaming the crate, an error will be raised with the message explaining why.
def rename(name)
response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CrateAPI::Crates::CRATE_ACTIONS[:rename] % ["#{self.id}"]}", :post, {:body => {:name => name}}))
raise CrateRenameError, response["message"] unless response["status"] != "failure"
end
+ # Add a file to the given crate object.
+ #
+ # @param [String] This is the path to the file that you wish to upload.
+ # @return [CrateFileAlreadyExistsError, nil] if there is an issue uploading the file to the crate, an error will be raised with the message explaining why.
def add_file(path)
file = File.new(path)
response = CrateAPI::Base.call("#{CrateAPI::Base::ITEMS_URL}/#{CrateAPI::Items::ITEM_ACTIONS[:upload]}", :post, {:body => {:file => file, :crate_id => @id}})
@@ -1,13 +1,28 @@
module CrateAPI
+ # Base class for Crate and Item objects
+ # @abstract Subclass in order to get the basic +:short_code+ , +:name+ , +:id+ params that every object should have.
class CrateObject
+ # @attr_reader [String] short_code short code for constructing the short url.
+ # @attr_reader [String] name name of the CrateObject that is being accessed.
+ # @attr_reader [Integer] id the numeric id of the CrateObject that is being accessed.
attr_reader :short_code, :name, :id
-
+
+ # The default initializer for the CrateObject class
+ #
+ # @param [Hash] a hash of values used to initialize the CrateObject.
+ # @option opts [String] :short_code short code for short url
+ # @option opts [String] :name name of the object
+ # @option opts [Integer] :id id of the object
+ # @return [CrateObject] this will return an initialized CrateObject instance.
def initialize(hash)
@short_code = hash["short_code"]
@name = hash["name"]
@id = hash["id"]
end
-
+
+ # Will return the shortened url of a given object
+ #
+ # @return [String] shortened url string for a given object.
def short_url
return "#{CrateAPI::Base::SHORT_URL}" % ["#{@short_code}"]
end
@@ -1,30 +1,48 @@
module CrateAPI
+ # CrateLimitReachedError class which is raised when the user can no longer add a crate to their account due to restriction.
class CrateLimitReachedError < Exception
end
+ # Crates class which is used to add, list, manipulate the Crates on a given account.
class Crates
+ # Hash of available actions to take upon the Crates endpoint.
CRATE_ACTIONS = {
:add => "add.json",
:list => "list.json",
:rename => "rename/%s.json",
:destroy => "destroy/%s.json"
}
+ # Add a new crate.
+ #
+ # @param [String] name of the crate to add.
+ # @return [nil] no output from this method is expected if everything goes right.
def add(name)
response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CRATE_ACTIONS[:add]}", :post, {:body => {:name => name}}))
raise CrateLimitReachedError, response["message"] unless response["status"] != "failure"
end
+ # Get a list of crates (w/o files).
+ #
+ # @return [Array] an array of crate objects.
+ # @note This will not return crate objects with the files they contain.
+ # @see Crates#all
def list
hash = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::CRATES_URL}/#{CRATE_ACTIONS[:list]}", :get))
return Crates.from_array(hash["crates"])
end
+ # Get a list of crates (w/ files).
+ #
+ # @return [Array] an array of crate objects.
def all
hash = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::ITEMS_URL}/#{CRATE_ACTIONS[:list]}", :get))
return Crates.from_array(hash["crates"])
end
+ # Class method to return an array of crate objects.
+ #
+ # @return [Array] an array of initialized Crate objects.
def self.from_array(array)
return [] unless array != nil
crates = Array.new
View
@@ -1,13 +1,24 @@
module CrateAPI
+ # FileDestroyError which is raised when there is an issue destroying the file.
class FileDestroyError < Exception
end
+
+ # Item class which is used to manipulate and represent a file blob which is inside of a Crate.
class Item < CrateObject
attr_reader :size
+ # Default initializer for the Item object.
+ #
+ # @param [Hash] hash an item hash.
+ # @return [CrateAPI::Item] a fully initialized Item object.
def initialize(hash)
super(hash)
@size = hash["size"]
end
+ # Will destroy the given file.
+ #
+ # @return [nil] this method should return nil if there are no issues.
+ # @raise [FileDestroyError] an error and message describing what happened.
def destroy
response = JSON.parse(CrateAPI::Base.call("#{CrateAPI::Base::ITEMS_URL}/#{CrateAPI::Items::ITEM_ACTIONS[:destroy] % ["#{self.id}"]}", :post))
raise FileDestroyError, response["message"] unless response["status"] != "failure"
@@ -1,12 +1,17 @@
module CrateAPI
+ # Items class which is used to get a set of items from the service.
class Items
+ # Hash of available actions to take upon the Items endpoint.
ITEM_ACTIONS = {
:upload => "upload.json",
:list => "list.json",
:show => "show/%s.json",
:destroy => "destroy/%s.json"
}
-
+ # Creates an array of Item objects.
+ #
+ # @param [Array] array to be used as the generation source.
+ # @return [Array] either an empty array if the input array is nil or a fully inialized array of Item objects.
def self.from_array(array)
return [] unless array != nil
files = Array.new

0 comments on commit 325da8d

Please sign in to comment.