shanesveller-webbynode-api 0.0.6 → 0.0.7

data/.document

@@ -1,5 +1,3 @@
 README.rdoc
 lib/**/*.rb
-bin/*
-features/**/*.feature
 LICENSE

data/.gitignore

@@ -3,3 +3,6 @@
 coverage
 rdoc
 pkg
+*.gem
+.yardoc
+doc

data/README.rdoc

@@ -11,6 +11,10 @@ All previous methods/initializers used named/ordered arguments. New API
 interactions are designed to use hashes of arguments instead. Older API
 models will be converted to this new design pattern soon.
 
+Also, any new/improved documentation will instead be visible in the
+{YARD documentation}[http://rdoc.info/projects/shanesveller/webbynode-api]
+hosted at {rdoc.info}[http://rdoc.info].
+
 == Currently Supported API functionality
 * Client information such as account status, contact/address info, credit
 * Webby information (status) and simple actions (start, shutdown, reboot)
@@ -62,8 +66,12 @@ models will be converted to this new design pattern soon.
   require 'webbynode-api'
   email = "example@email.com"
   api_key = "1234567890abcdef"
-  @new_zone = WebbyNode::DNS.new_zone(:email => email, :token => token, :domain => "mynewdomain.com.", :ttl => 86400)
+  @new_zone = WebbyNode::DNS.new_zone(:email => email, :token => api_key, :domain => "mynewdomain.com.", :ttl => 86400)
   pp @new_zone["id"]
+  # => 171
+
+  WebbyNode::DNS.delete_zone(:email => email, :token => api_key, :id => 171)
+  # => true
 
 == Copyright
 

data/Rakefile

@@ -54,3 +54,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end

data/VERSION

@@ -1 +1 @@
-0.0.6
+0.0.7

data/lib/webbynode-api/data.rb

@@ -1,5 +1,8 @@
 class WebbyNode
   # Represents the account-holder's information
+  #
+  # @author Shane Sveller
+  # @since 0.0.1
   class Client < WebbyNode::APIObject
     def initialize(email, api_key)
       super(email, api_key)
@@ -9,11 +12,23 @@ class WebbyNode
 
   # Represents an individual webby with status, reboot/shutdown/start functionality
   # via +method_missing+
+  # 
+  # @author Shane Sveller
+  # @since 0.0.1
   class Webby < WebbyNode::APIObject
     attr_accessor :hostname
 
-    # Optionally takes a hostname as the third argument to fetch just that Webby.
-    # Leaving this nil set @data to an array of all the account's webbies
+    # Fetches either an array of Webbies' data or an individual Webby's data.
+    #
+    # @param [String] email E-mail address used for API access
+    # @param [String] api_key API token used for API access
+    # @param [optional, String] hostname Hostname used to look up an individual
+    #   Webby. When absent or nil, the newly instantiated object instead
+    #   represents an Array of Webbies.
+    # @example Fetch data for a Webby named "webby1"
+    #   WebbyNode::Webby.new(email, api_key, "webby1")
+    # @example Fetch an Array of Webbies
+    #   WebbyNode::Webby.new(email, api_key)
     def initialize(email, api_key, hostname = nil)
       super(email, api_key)
       if hostname
@@ -23,6 +38,8 @@ class WebbyNode
       end
     end
 
+    # Provides status, start/shutdown/reboot functionality for an individual
+    # Webby. Provides list functionality for an Array of Webbies.
     def method_missing(method)
       if method.to_s == "status"
         return auth_get("/api/xml/webby/#{@hostname}/status")["hash"]["status"]
@@ -31,16 +48,25 @@ class WebbyNode
       elsif method.to_s == "list"
         return @data
       else
-        raise "No such action possible on a Webby."
+        raise ArgumentError, "No such action possible on a Webby."
       end
     end
   end
 
+  # Represents the DNS zones present on the API account
+  #
+  # @author Shane Sveller
+  # @since 0.0.2
   class DNS < WebbyNode::APIObject
+    # Holds the ID used internally at WebbyNode that represents a given zone.
     attr_accessor :id
 
-    # Optionally takes an ID as the third argument to fetch just that zone. Without,
-    # you get an array of all zones.
+    # Fetches either a single zone or an Array of all zones based on the presence
+    # of the id parameter.
+    #
+    # @param [String] email E-mail address used for API access
+    # @param [String] api_key API token used for API access
+    # @param [option, Integer] id ID that represents an individual zone
     def initialize(email, api_key, id = nil)
       super(email, api_key)
       if id
@@ -51,11 +77,21 @@ class WebbyNode
       end
     end
 
+    # @since 0.0.3
+    # @return [Array<Hash>] Array of a zones' records, each individually is a Hash.
     def records
       raise "This method should only be called on DNS instances with an id" unless @id
       auth_get("/api/xml/dns/#{@id}/records")["hash"]["records"]
     end
 
+    # @since 0.0.6
+    # @option options [String] :email E-mail address used for API access
+    # @option options [String] :token API token used for API access
+    # @option options [optional, String] :status Optional argument to set the
+    #   status of the zone. Valid values include 'Active' or 'Inactive' only.
+    # @return [Hash] Hash of the new zone's information
+    # @raise [ArgumentError] Raises ArgumentError if :token, :email, :domain,
+    #   or :ttl are missing from the options parameter.
     def self.new_zone(options = {})
       raise ArgumentError, "API access information via :email and :token are required arguments" unless options[:email] && options[:token]
       raise ArgumentError, ":domain and :ttl are required arguments" unless options[:domain] && options[:ttl]
@@ -73,6 +109,13 @@ class WebbyNode
       return zone_data["hash"]
     end
 
+    # @since 0.0.6
+    # @option options [String] :email E-mail address used for API access
+    # @option options [String] :token API token used for API access
+    # @option options [Integer] :id WebbyNode's internally-used ID that idenftifies the zone
+    # @return [Boolean] Returns true upon succesful deletion of the zone.
+    # @raise [ArgumentError] Raises ArgumentError if :token, :email, or :id are
+    # missing from the options parameter.
     def self.delete_zone(options = {})
       raise ArgumentError, "API access information via :email and :token are required arguments" unless options[:email] && options[:token]
       raise ArgumentError, ":id is a required argument" unless options[:id]

data/lib/webbynode-api.rb

@@ -2,21 +2,38 @@ require 'rubygems'
 gem 'httparty'
 require 'httparty'
 
+# @author Shane Sveller
 class WebbyNode
+
+  # @author Shane Sveller
+  # @since 0.0.1
   class APIObject
     include HTTParty
     base_uri "https://manager.webbynode.com"
     format :xml
 
-    attr_accessor :email, :api_key, :data
+    # E-mail address used to access the WebbyNode API
+    attr_accessor :email
+    # API token used to access the WebbyNode API, visible at https://manager.webbynode.com/account
+    attr_accessor :api_key
+    # Stores the results of the HTTParty API interactions
+    attr_accessor :data
 
     # Creates a new API object secured by e-mail address and API token
+    #
+    # @param [String] email e-mail address with API access
+    # @param [String] api_key API token that matches the included e-mail address
+    # @example Instantiates a new API access object
+    #   WebbyNode::APIObject.new("example@email.com", "123456abcdef")
     def initialize(email, api_key)
       @email = email
       @api_key = api_key
     end
 
     # Uses HTTParty to submit a secure API request via email address and token
+    # @param [String] url URL to GET using HTTParty
+    # @param [Hash] options Hash of additional HTTParty parameters
+    # @option options [Hash] :query query hash used to build the final URL
     def auth_get(url, options = {})
       raise ArgumentError, "API information is missing or incomplete" unless @email && @api_key
       options[:query] ||= {}
@@ -30,6 +47,19 @@ class WebbyNode
       self.class.auth_post(url, options)
     end
 
+    # Uses HTTParty to submit a secure API POST request via email address and token.
+    # API access information should be included via the :email and :token hash keys,
+    # in a hash on the :query key of the options hash passed as the second argument
+    # in the method call.
+    #
+    # @param [String] url The URL to post to using HTTParty
+    # @option options [String] :query query hash used to build the final URL
+    #   Should include :email and :token keys with the e-mail address
+    #   and API token with access rights
+    # @return [Hash] returns a Hash of nested XML elements using string-based keys
+    # @example Queries the API data for the client account
+    #   WebbyNode::APIObject.auth_post("/api/xml/client", :query => {:email => ""example@email.com",
+    #   :token => "1234567abcde", :posted_data => "test"})
     def self.auth_post(url, options = {})
       options[:query] ||= {}
       raise ArgumentError, "API information is missing or incomplete" unless options[:query][:email] && options[:query][:token]
@@ -39,6 +69,11 @@ class WebbyNode
     end
 
     # Catches simple requests for specific API data returned via a hash
+    #
+    # @return [Object, nil] If the @data instance variable is set, and contains a hash
+    #   with a key matching the missing method, return the value from that hash key.
+    #   Said value may be typecast into a Ruby object if the XML is formatted properly.
+    #   Otherwise returns nil.
     def method_missing(method)
       key = @data[method.to_s] if @data
       key

data/webbynode-api.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{webbynode-api}
-  s.version = "0.0.6"
+  s.version = "0.0.7"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Shane Sveller"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: shanesveller-webbynode-api
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors: 
 - Shane Sveller