shanesveller-webbynode-api 0.1.2 → 0.2.0

data/README.markdown

@@ -6,71 +6,41 @@ design document for the API itself are available
 [here](http://howto.webbynode.com/topic.php?id=25). Functionality
 is currently based on the API guide version 2.
 
-##Notice
-**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)
 * List all webbies
 * DNS zone information such as domain name, TTL, and status
+* List of all individual records in a given DNS zone
 * Creation/deletion of DNS zones
-
-##In Development
-* DNS record information such as type, data, name, id, and TTL
+* Activation/deactivation of DNS zones
 
 ##Planned Features
-* DNS zone/record creation, editing and deletion
+* DNS record creation, editing and deletion
 * Whatever else WebbyNode gives us in the API :)
 
-##Example Usage
-###Account
-    require 'webbynode-api'
-    email = "example@email.com"
-    api_key = "1234567890abcdef"
-    @client = WebbyNode::Client.new(email, api_key)
-    puts @client.firstname
-
-###Webby
-    require 'webbynode-api'
-    email = "example@email.com"
-    api_key = "1234567890abcdef"
-    hostname = "webby1"
-    # Get a single Webby's info
-    @webby = WebbyNode::Webby.new(email, api_key, hostname)
-    @webby.status
-    @webby.shutdown
-    @webby.status
-    # Get a list of all Webbies
-    @webbies = WebbyNode::Webby.new(email, api_key)
-    puts @webbies.list
-
-###DNS
-    require 'webbynode-api'
-    email = "example@email.com"
-    api_key = "1234567890abcdef"
-    zone_id = 123
-    @dns = WebbyNode::DNS.new(email, api_key)
-    pp @dns.zones
-    @dns = WebbyNode::DNS.new(email, api_key, zone_id)
-    pp @dns.domain
-    pp @dns.records
+##Usage and Examples
+###Command-Line Utility
+This gem now includes a basic commandline utility named `webby`.
+You can pass your email and token as commandline options, or place them
+in a YAML file in `~/.webbynode.yml`, like so:
+    email: example@email.com
+    token: 123456abcdef
+You can then use the commandline utility like so
+    webby -a webby status webby1
+    webby -a webby restart webby1
+If you do not create the YAML file, the above lines might look like:
+    webby -email example@email.com -token 123456abcdef -a webby status webby1
+    webby -email example@email.com -token 123456abcdef -a webby restart webby1
+###Gem Usage
+**Please visit the
+[YARD documentation](http://rdoc.info/projects/shanesveller/webbynode-api)
+hosted at [rdoc.info](http://rdoc.info) for usage, documentation and examples.**
 
-###DNS Zone Creation/Deletion
-    require 'webbynode-api'
-    email = "example@email.com"
-    api_key = "1234567890abcdef"
-    @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
+Alternately, the YARD docs can be generated and viewed locally if you have the
+`yard` gem installed.
+    rake yardoc
+    open doc/index.html
 
 ##Copyright
 

data/Rakefile

@@ -9,6 +9,8 @@ begin
     gem.email = "shanesveller@gmail.com"
     gem.homepage = "http://github.com/shanesveller/webbynode-api"
     gem.authors = ["Shane Sveller"]
+    gem.add_dependency('httparty', '>= 0.4.3')
+    gem.add_dependency('optiflag', '>= 0.6.5')
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
 

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/bin/webby

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+gem 'optiflag'
+require 'optiflag'
+require 'lib/webbynode-api'
+
+module WebbyNodeTool extend OptiFlagSet
+  optional_flag "email"
+  optional_flag "token"
+  flag "act" do
+    alternate_forms "action","A","a"
+    description "API action to be taken, in the form of <type> <action> <target>"
+    arity 3
+  end
+  optional_flag "verbose" do
+    no_args
+    alternate_forms "V","v"
+  end
+
+  and_process!
+end
+
+VERBOSE = ARGV.flags.verbose?
+
+if !ARGV.flags.email? || !ARGV.flags.token
+  yaml_config = File.join(ENV['HOME'],'.webbynode.yml')
+  if File.exist?(yaml_config)
+    puts "Loading API credentials from #{yaml_config}..." if VERBOSE
+    CONFIG = YAML.load_file yaml_config
+    EMAIL = CONFIG["email"]
+    TOKEN = CONFIG["token"]
+  else
+    puts "Email or token parameter missing and no config file exists at ~/.webbynode.yml"
+  end
+else
+  EMAIL = ARGV.flags.email
+  TOKEN = ARGV.flags.token
+end
+
+type = ARGV.flags.act[0]
+action = ARGV.flags.act[1]
+target = ARGV.flags.act[2]
+case type
+when "webby" then
+  case action
+    when "status"
+      puts "Webby Status: #{target}: " + WebbyNode::Webby.new(:email => EMAIL, :token => TOKEN, :hostname => target).status
+    when "restart", "start"
+      puts "#{action.capitalize}ing Webby: #{target}..."
+      puts "Job ID: " + WebbyNode::Webby.new(:email => EMAIL, :token => TOKEN, :hostname => target).send(action).to_s
+    when "shutdown"
+      puts "Shutting Down Webby: #{target}..."
+      puts "Job ID: " + WebbyNode::Webby.new(:email => EMAIL, :token => TOKEN, :hostname => target).send(action).to_s
+    else
+      puts "Not a valid action for webby #{target}."
+  end
+else
+  puts "Valid options for type:"
+  %w(webby).each {|type| puts type.capitalize }
+end

data/lib/webbynode-api/data.rb

@@ -5,6 +5,13 @@ class WebbyNode
   # @since 0.0.1
   # @version 0.1.0
   class Client < WebbyNode::APIObject
+    # Fills the @data variable with a hash of information about the client.
+    #
+    # @option options [String] :email E-mail address used for API access
+    # @option options [String] :token API token used for API access
+    # @example Get amount of credit left on an account
+    #   @client = WebbyNode::Client.new(:email => email, :token)
+    #   pp @client.credit # => 1.5
     def initialize(options = {})
       super(options)
       @data = auth_get("/api/xml/client")["hash"]["client"]
@@ -42,8 +49,6 @@ class WebbyNode
         return auth_get("/api/xml/webby/#{@hostname}/status")["hash"]["status"]
       elsif %w(start shutdown reboot).include? method.to_s
         return auth_get("/api/xml/webby/#{@hostname}/#{method.to_s}")["hash"]["job_id"]
-      elsif method.to_s == "list"
-        return @data
       else
         raise ArgumentError, "No such action possible on a Webby."
       end

data/lib/webbynode-api/dns.rb

@@ -66,8 +66,19 @@ class WebbyNode
       # @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.
+      # @example Create a zone with the domain example.com and TTL of 86400
+      #   WebbyNode::DNS::Zone.create_zone({
+      #     :email => email, :token => token,
+      #     :domain => "example.com.", :ttl => 86400
+      #   })
+      # @example Create an *inactive* zone with the domain example.com and TTL of 86400
+      #   WebbyNode::DNS::Zone.create_zone({
+      #     :email => email, :token => token,
+      #     :domain => "example.com.", :ttl => 86400,
+      #     :status => "Inactive"
+      #   })
       def self.create_zone(options = {})
-        raise ArgumentError, "API access information via :email and :token are required arguments" unless options[:email] && options[:token]
+        raise ArgumentError, ":email and :token are required arguments for API access" unless options[:email] && options[:token]
         raise ArgumentError, ":domain and :ttl are required arguments" unless options[:domain] && options[:ttl]
         if options[:status]
           raise ArgumentError, ":status must be 'Active' or 'Inactive'" unless %w(Active Inactive).include? options[:status]
@@ -89,9 +100,15 @@ class WebbyNode
       # @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.
+      #   missing from the options parameter.
+      # @example Delete a zone with ID of 100
+      #   WebbyNode::DNS::Zone.delete_zone({
+      #     :email => email, :token => token,
+      #     :id => 100
+      #   })
+      #   # => true
       def self.delete_zone(options = {})
-        raise ArgumentError, "API access information via :email and :token are required arguments" unless options[:email] && options[:token]
+        raise ArgumentError, ":email and :token are required arguments for API access" unless options[:email] && options[:token]
         raise ArgumentError, ":id is a required argument" unless options[:id]
         return auth_post("/api/xml/dns/#{options[:id]}/delete", :query => options)["hash"]["success"]
       end
@@ -119,6 +136,13 @@ class WebbyNode
     # @since 0.1.1
     # @version 0.1.0
     class RecordList < WebbyNode::APIObject
+      # Fills the @data variable with an Array of Hashes containing individual
+      # DNS records in a zone.
+      #
+      # @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 ID used internally by WebbyNode to identify the zone
+      # @raise [ArgumentError] Raises ArgumentError if :email, :token, or :id are absent from options
       def initialize(options = {})
         raise ArgumentError, ":id is a required argument" unless options[:id]
         super(options)
@@ -126,5 +150,41 @@ class WebbyNode
         @data = auth_get("/api/xml/dns/#{@id}/records")["hash"]["records"]
       end
     end
+
+    # Represents a single DNS record
+    #
+    # @author Shane Sveller
+    # @since 0.1.3
+    # @version 0.1.0
+    class Record < WebbyNode::APIObject
+      def initialize(options = {})
+        raise ArgumentError, ":id is a required argument" unless options[:id]
+        super(options)
+        @id = options[:id]
+        @data = auth_get("/api/xml/records/#{@id}")["hash"]["record"]
+      end
+
+      # Creates a new DNS record
+      #
+      # @option options [String] :email E-mail address used for API access
+      # @option options [String] :token API token used for API access
+      # @option options [String] :type DNS record type i.e. A, CNAME or MX
+      # @option options [String] :data DNS record data, typically an IP address
+      def self.create(options = {})
+        raise ArgumentError, ":email and :token are required arguments for API access" unless options[:email] && options[:token]
+        raise ArgumentError, ":data and :type are required arguments" unless options[:data] && options[:type]
+        valid_types = %w(A CNAME MX)
+        raise ArgumentError, "#{options[:type]} is not a valid value for :type" unless valid_types.include?(options[:type])
+        @id = options[:id]
+        options.delete(:id)
+        for key in options.keys
+          if %w(type name data aux ttl).include? key.to_s
+            options["record[#{key.to_s}]"] = options[key]
+            options.delete(key)
+          end
+        end
+        return auth_post("/api/xml/dns/#{@id}/records/new", :query => options)["hash"]["record"]
+      end
+    end
   end
 end

data/test/data/new-record.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<hash>
+  <record>
+    <type>A</type>
+    <ttl type="integer">86400</ttl>
+    <aux type="integer">0</aux>
+    <data>111.222.111.222</data>
+    <name></name>
+    <id type="integer">181</id>
+  </record>
+</hash>

data/test/dns_test.rb

@@ -53,8 +53,9 @@ class WebbyNodeDNSTest < Test::Unit::TestCase
       FakeWeb.register_uri(:post, /^https:\/\/manager\.webbynode\.com\/api\/xml\/dns\/new\?.+/i, :body => File.read("#{data_path}/new-zone.xml"))
     end
     should "raise ArgumentError if API information isn't present" do
-      assert_raise(ArgumentError,"API access information via :email and :token are required arguments"){ WebbyNode::DNS::Zone.create_zone(:token => @token, :domain => @domain, :ttl => @ttl) }
-      assert_raise(ArgumentError,"API access information via :email and :token are required arguments"){ WebbyNode::DNS::Zone.create_zone(:email => @email, :domain => @domain, :ttl => @ttl) }
+      assert_raise(ArgumentError,":email and :token are required arguments for API access"){ WebbyNode::DNS::Zone.create_zone(:token => @token, :domain => @domain, :ttl => @ttl) }
+      assert_raise(ArgumentError,":email and :token are required arguments for API access"){ WebbyNode::DNS::Zone.create_zone(:email => @email, :domain => @domain, :ttl => @ttl) }
+      assert_raise(ArgumentError,":email and :token are required arguments for API access"){ WebbyNode::DNS::Zone.create_zone(:domain => @domain, :ttl => @ttl) }
     end
     should "raise ArgumentError if :domain or :ttl aren't included in method call" do
       assert_raise(ArgumentError, ":domain and :ttl are required arguments"){ WebbyNode::DNS::Zone.create_zone(:email => @email, :token => @token, :ttl => @ttl) }
@@ -140,4 +141,43 @@ class WebbyNodeDNSTest < Test::Unit::TestCase
       record["type"].should == "A"
     end
   end
+  context "creating a DNS record" do
+    setup do
+      @email = "example@email.com"
+      @token = "123456"
+      @id = 1
+      data_path = File.join(File.dirname(__FILE__), "data")
+      FakeWeb.clean_registry
+      FakeWeb.register_uri(:post, /^https:\/\/manager\.webbynode\.com\/api\/xml\/dns\/\d+\/records\/new\?.+/i, :body => File.read("#{data_path}/new-record.xml"))
+    end
+    should "raise ArgumentError if :id argument is absent" do
+      assert_raise(ArgumentError, ":id is a required argument"){ WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => nil)}
+      assert_nothing_raised { WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :type => "A", :data => "111.222.111.222")}
+    end
+    should "raise ArgumentError if :type or :data are absent" do
+      assert_raise(ArgumentError, ":data and :type are required arguments"){ WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :data => "111.222.111.222") }
+      assert_raise(ArgumentError, ":data and :type are required arguments"){ WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :type => "A") }
+      assert_nothing_raised { WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :type => "A", :data => "111.222.111.222")}
+    end
+    should "accept only valid record types" do
+      for record_type in %w(A CNAME MX) do
+        assert_nothing_raised { WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :type => record_type, :data => "111.222.111.222")}
+      end
+      for bad_type in %w(SPF RDNS spam type blah)
+        assert_raise(ArgumentError, "#{bad_type} is not a valid value for :type"){ WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :type => bad_type, :data => "111.222.111.222")}
+      end
+    end
+    should "return a Hash of the new record's data" do
+      @new_record = WebbyNode::DNS::Record.create(:email => @email, :token => @token, :id => @id, :type => "A", :data => "111.222.111.222")
+      @new_record.is_a?(Hash).should be(true)
+      @new_record["type"].should == "A"
+      @new_record["data"].should == "111.222.111.222"
+      for key in %w(type ttl aux data name id)
+        @new_record.keys.include?(key).should be(true)
+      end
+      @new_record
+    end
+  end
+  context "fetching a DNS record" do
+  end
 end

data/test/webby_test.rb

@@ -29,6 +29,9 @@ class WebbyNodeWebbyTest < Test::Unit::TestCase
       FakeWeb.register_uri(:get, /^https:\/\/manager\.webbynode\.com\/api\/xml\/webby\/\w+\/status\?.+/i, :body => File.read("#{data_path}/webby-status-reboot.xml"))
       @webby.status.should == "Rebooting"
     end
+    should "raise ArgumentError if a bad method is called" do
+      assert_raise(ArgumentError, "No such action possible on a Webby."){ @webby.restart }
+    end
   end
   context "fetching webbies data from API" do
     setup do

data/webbynode-api.gemspec

@@ -2,25 +2,26 @@
 
 Gem::Specification.new do |s|
   s.name = %q{webbynode-api}
-  s.version = "0.1.2"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Shane Sveller"]
   s.date = %q{2009-07-13}
+  s.default_executable = %q{webby}
   s.email = %q{shanesveller@gmail.com}
+  s.executables = ["webby"]
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.markdown",
-     "README.rdoc"
+     "README.markdown"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
      "README.markdown",
-     "README.rdoc",
      "Rakefile",
      "VERSION",
+     "bin/webby",
      "lib/webbynode-api.rb",
      "lib/webbynode-api/data.rb",
      "lib/webbynode-api/dns.rb",
@@ -34,6 +35,7 @@ Gem::Specification.new do |s|
      "test/data/dns-1.xml",
      "test/data/dns-records.xml",
      "test/data/dns.xml",
+     "test/data/new-record.xml",
      "test/data/new-zone.xml",
      "test/data/webbies.xml",
      "test/data/webby-reboot.xml",
@@ -67,8 +69,14 @@ Gem::Specification.new do |s|
     s.specification_version = 2
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<httparty>, [">= 0.4.3"])
+      s.add_runtime_dependency(%q<optiflag>, [">= 0.6.5"])
     else
+      s.add_dependency(%q<httparty>, [">= 0.4.3"])
+      s.add_dependency(%q<optiflag>, [">= 0.6.5"])
     end
   else
+    s.add_dependency(%q<httparty>, [">= 0.4.3"])
+    s.add_dependency(%q<optiflag>, [">= 0.6.5"])
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: shanesveller-webbynode-api
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Shane Sveller
@@ -10,27 +10,45 @@ bindir: bin
 cert_chain: []
 
 date: 2009-07-13 00:00:00 -07:00
-default_executable: 
-dependencies: []
-
+default_executable: webby
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: optiflag
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.5
+    version: 
 description: 
 email: shanesveller@gmail.com
-executables: []
-
+executables: 
+- webby
 extensions: []
 
 extra_rdoc_files: 
 - LICENSE
 - README.markdown
-- README.rdoc
 files: 
 - .document
 - .gitignore
 - LICENSE
 - README.markdown
-- README.rdoc
 - Rakefile
 - VERSION
+- bin/webby
 - lib/webbynode-api.rb
 - lib/webbynode-api/data.rb
 - lib/webbynode-api/dns.rb
@@ -44,6 +62,7 @@ files:
 - test/data/dns-1.xml
 - test/data/dns-records.xml
 - test/data/dns.xml
+- test/data/new-record.xml
 - test/data/new-zone.xml
 - test/data/webbies.xml
 - test/data/webby-reboot.xml

data/README.rdoc

@@ -1,78 +0,0 @@
-= webbynode-api
-
-This gem wraps the API available for the VPS hosting company
-{WebbyNode}[http://www.webbynode.com]. Details and a preliminary
-design document for the API itself are available
-{here}[http://howto.webbynode.com/topic.php?id=25]. Functionality
-is currently based on the API guide version 2.
-
-== Notice
-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)
-* List all webbies
-* DNS zone information such as domain name, TTL, and status
-* Creation/deletion of DNS zones
-
-== In Development
-* DNS record information such as type, data, name, id, and TTL
-
-== Planned Features
-* DNS zone/record creation, editing and deletion
-* Whatever else WebbyNode gives us in the API :)
-
-== Example Usage
-=== Account
-  require 'webbynode-api'
-  email = "example@email.com"
-  api_key = "1234567890abcdef"
-  @client = WebbyNode::Client.new(email, api_key)
-  puts @client.firstname
-
-=== Webby
-  require 'webbynode-api'
-  email = "example@email.com"
-  api_key = "1234567890abcdef"
-  hostname = "webby1"
-  # Get a single Webby's info
-  @webby = WebbyNode::Webby.new(email, api_key, hostname)
-  @webby.status
-  @webby.shutdown
-  @webby.status
-  # Get a list of all Webbies
-  @webbies = WebbyNode::Webby.new(email, api_key)
-  puts @webbies.list
-
-=== DNS
-  require 'webbynode-api'
-  email = "example@email.com"
-  api_key = "1234567890abcdef"
-  zone_id = 123
-  @dns = WebbyNode::DNS.new(email, api_key)
-  pp @dns.zones
-  @dns = WebbyNode::DNS.new(email, api_key, zone_id)
-  pp @dns.domain
-  pp @dns.records
-
-=== DNS Zone Creation/Deletion
-  require 'webbynode-api'
-  email = "example@email.com"
-  api_key = "1234567890abcdef"
-  @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
-
-Copyright (c) 2009 Shane Sveller. See LICENSE for details.