domain_tools 0.0.1

data/examples/1_prepare.rb

@@ -0,0 +1,49 @@
+# ----------------------------------------------------------------------------- 
+# 1. PREPARE THE ENVIRONMENT
+# -----------------------------------------------------------------------------
+
+# 1.A Define settings step by step  
+# This a a clear way to define each settings
+DomainTools::use(DOMAINTOOLS_USERNAME,DOMAINTOOLS_KEY)
+DomainTools::get("whois")
+DomainTools::as("json")
+DomainTools::on("domaintools.com")
+DomainTools::where("var1=value1&var2=value2")
+
+# 1.B All in one with a hash
+# Useful to separate in a settings file your default configuration
+DomainTools::with({
+  :username   => DOMAINTOOLS_USERNAME,
+  :key        => DOMAINTOOLS_KEY,         
+  :service    => "whois",
+  :format     => "json",
+  :domain     => "domaintools.com",
+  :parameters => "var1=value1&var2=value2"
+})     
+
+# 1.C Inline
+# Each call can be chained, useful in some case to gain spaces in your code
+DomainTools::use(DOMAINTOOLS_USERNAME,DOMAINTOOLS_KEY)
+DomainTools::get("whois")::as("json")::on("domaintools.com")
+
+# -----------------------------------------------------------------------------
+# TIPS
+# -----------------------------------------------------------------------------
+# The parameters (set with the static call "where" or with the hash
+# key "parameters") can either be a string or a Hash.
+# If a hash is provided, it will be merged in a string before request execution
+                   
+# Using the "where" call to specify the parameters 
+DomainTools::where({
+  :var1 => "value1",
+  :var2 => "value2"  
+})
+
+# Or using the "with" (hash) settiings method and the key "parameters"
+DomainTools::with({
+  # ...
+  :parameters => {
+    :var1 => "value1",
+    :var2 => "value2"  
+  }
+})

data/examples/2_response.rb

@@ -0,0 +1,31 @@
+# -----------------------------------------------------------------------------
+# 2. GET RAW API RESULT (JSON, XML or HTML)
+# -----------------------------------------------------------------------------
+# Note: each of these examples assume that "prepare" step (see example 1.)
+# has been done with valid credentials
+
+
+# 2.A The "step by step" way
+request         = DomainTools.request   # Get a request object
+request.format  = "json" #xml,html      # Define the response format
+request.domain  = "domaintools.com"     # Define the domain
+response        = request.do            # Execute the request
+@example1       = response.to_s         # Save the raw result in a variable
+
+# 2.B You can do the same but inline
+@example2       = DomainTools::as("json")::on("domaintools.com").do.to_s
+
+# -----------------------------------------------------------------------------
+# TIPS
+# -----------------------------------------------------------------------------
+# There are aliases for each method on each DomainTools related object.
+# It allows you to use great shortcuts to quickly write requests
+
+# Here is 3 line doing exactly the same thing :
+# - Create a request (with default settings provided)
+# - Execute the request
+# - Return a Response object
+
+@example3       = DomainTools.request.response 
+@example4       = DomainTools.request.do
+@example5       = DomainTools.do

data/examples/3_browsing.rb

@@ -0,0 +1,36 @@
+# -----------------------------------------------------------------------------
+# 3. BROWSE AN API RESPONSE
+# -----------------------------------------------------------------------------
+# Note: each of these examples assume that "prepare" step (see example 1.)
+# has been done with valid credentials
+
+
+# 3.A The "do it yourself" way
+# get the raw result (json)
+request         = DomainTools.request
+request.format  = "json" # (or xml)
+response        = request.response
+# Use JSON.decode to parse the result (REXML for xml, for example)
+hash            = ActiveSupport::JSON.decode(response.content)    
+# Simply use it as a Hash
+@example1       = hash["response"]["registration"]["registrar"]
+                         
+
+# 3.B The "auto parse" way
+# get the response (without even knowing the request format!)
+response  = DomainTools.request.response
+# The DomainTools wrapper will parse the result automaticaly
+# You can now use to_hash method to get a hash and use it
+@example2 = response.to_hash["response"]["registration"]["registrar"]
+
+
+# 3.C The short way, inline
+# Like always, you can do this inline!
+@example3 = DomainTools.request.do["response"]["registration"]["registrar"]
+
+
+# -----------------------------------------------------------------------------
+# TIPS
+# -----------------------------------------------------------------------------
+# Using the direct browsing of the hash assumes you are sure of the response
+# structure. Some tests for nil values can be useful!  

data/examples/4_error.rb

@@ -0,0 +1,40 @@
+# -----------------------------------------------------------------------------
+# 4. ERROR HANDLING
+# -----------------------------------------------------------------------------
+# Note: each of these examples assume that "prepare" step (see example 1.)
+# has been done with valid credentials
+
+# 4.A When you execute a request, it can raise an exception, you need
+# to be ready to catch it.
+begin
+  request         = DomainTools.request
+  request.domain  = "domaintoolscom"          # This is not a valid domain
+  request.response                            # Execute the request
+  # here an execption will be thrown, we'll fallback to the rescue part
+  @example1       = "I will never be seen"
+rescue DomainTools::ServiceException => e
+  if request.error?                           # test if there is an error
+    @example1 = "#{e.class}: #{request.error}"
+    # you can also get the error code with  request.error.code
+    # and the error message with            request.error.message
+  else
+    @example1 = "The request has no error but raises an exception. Unlikely to hapenned"
+  end
+end                                    
+
+# ----------------------------------------------------------------------------- 
+# TIPS
+# -----------------------------------------------------------------------------
+# Here is the list of possible exceptions (and their inheritance)
+
+# ServiceException                < StandardError
+# NoSettingsException             < ServiceException
+# NoCredentialsException          < ServiceException
+# BadRequestException             < ServiceException
+# NotAuthorizedException          < ServiceException
+# NotFoundException               < ServiceException
+# InternalServerErrorException    < ServiceException
+# ServiceUnavailableException     < ServiceException
+# WrongParmatersException         < ServiceException
+# NoDomainException               < ServiceException
+# UnknownException                < ServiceException

data/examples/5_complete.rb

@@ -0,0 +1,49 @@
+# -----------------------------------------------------------------------------
+# 5. SYNTAX & FORMAT FLEXIBILITY
+# -----------------------------------------------------------------------------
+
+# The idea behind this wrapper is to allow you to choose the syntax that feets your style.
+# The lib will assume for you that you need to start a request only when you print or browse a response.
+# You can use the module itself, the request or the response and ask for format changes or object browsing,
+# it will just do the effort for you and prepare/execute/parse the whole request
+# Here down a complete example of requests, responses, tests...
+                                                               
+                                                               
+# Set credentials and create a new request
+request = DomainTools::use(DOMAINTOOLS_USERNAME,DOMAINTOOLS_KEY).request
+# Set the domain
+request.domain  = "domaintools.com"
+# Set the format
+request.format  = "json"
+# Execute the request (and then get a json result)
+begin
+  @example1       = request.do.to_s
+  # Recreate a valid xml with the parsed json (no new request made)
+  @example2       = request.to_xml!
+  # print some debug  as yaml
+  puts request.to_yaml
+  # finally just get a specific data 
+  begin
+    @example3       = request["response"]["registrant"]["name"]
+  rescue NoMethodError => e # If you try to browse nil
+    @example3       = "Unable to find registrant name"
+  end
+  # Note: Despite all manipulations, only ONE API request has been made
+  # We change the service
+  request.service = "hosting-history"                                 
+  # And the response format
+  request.format  = "xml"
+  # And we force a new request with ("do!" instead of "do")
+  @example4       = request.do!
+  begin
+    @example5 = request["response"]["ip_history"].first["actiondate"]
+  rescue NoMethodError => e
+    @example5 = "No IP history"
+  end
+rescue  DomainTools::ServiceException => e
+  if request && request.error?
+    @error = "#{e.class}: #{request.error}"
+  else
+    @error = "Unknown error: #{e.message}"
+  end
+end

data/lib/domain_tools/core.rb

@@ -0,0 +1,137 @@
+module DomainTools
+  extend self
+  include Exceptions
+  
+  # Authentication of the user       
+  # can be set with a hash {:username,:password} as one param
+  # or with two string params
+  def self.use(credentials,key=false)
+    if credentials.kind_of? Hash
+      self.set_data :username,  credentials[:username]
+      self.set_data :key,       credentials[:key]
+    else                        
+      self.set_data :username,  credentials
+      self.set_data :key,       key
+    end
+    self
+  end      
+  
+  def self.clear
+    @data = {}
+    @request = nil
+    self
+  end
+  
+  # Select which service must be called for this request
+  def self.get(service)
+    self.set_data :service, service
+  end             
+  
+  def self.sign(active)
+    self.set_data :signed, active
+  end
+  
+  # change the format of the response (only XML or JSON)
+  def self.as(format)           
+    self.set_data :format, format
+  end
+  
+  # to specify parameters to the service
+  def self.where(parameters)
+    self.set_data :parameters, parameters
+  end
+  
+  # to overide settings, only for specific cases or for testing
+  def self.with(settings={})                                      
+    settings.each{|key, value| set_data(key,value)}
+    self
+  end
+  
+  # Param of the request, usually a domain name or sometime the first part of a domain
+  def self.on(domain)
+    self.set_data :domain, domain
+  end
+    
+  # check first, raise exception if needed, execute the HTTP request
+  def self.do
+    self.request.do
+  end 
+
+  def self.response
+    self.do
+  end
+  
+  def self.request
+    raise DomainTools::NoSettingsException unless @request
+    @request
+  end
+  
+  def self.counter
+    return 0 unless @counter
+    @counter
+  end
+  
+  def self.counter!
+    @counter = 0 unless @counter
+    @counter+=1
+  end
+
+  def self.[](key)
+    self.do unless self.done?
+    self.request[key]
+  end
+  
+  # Request aliases
+  
+  def self.done?
+    self.request.done?
+  end
+  
+  def self.error?
+    self.request.error?
+  end
+  
+  def self.success?
+    self.request.success?
+  end  
+  
+  def self.to_s
+    self.request.to_s
+  end 
+  
+  def self.to_hash
+    self.request.to_hash
+  end
+  
+  def self.to_json
+    self.request.to_json
+  end
+  
+  def self.to_json!
+    self.request.to_json!
+  end
+  
+  def self.to_xml
+    self.request.to_xml
+  end
+      
+  def self.to_xml! 
+    self.request.to_xml!       
+  end 
+  
+  def self.to_yaml
+    self.request.to_yaml
+  end         
+  
+  private
+  
+  def self.set_data(key,val)
+    @data = {} unless @data
+    @data[key.to_sym] = val
+    # Update data for future request
+    @request = DomainTools::Request.new @data
+    self
+  end
+  
+  
+end

data/lib/domain_tools/error.rb

@@ -0,0 +1,40 @@
+module DomainTools
+  class Error
+    
+    def initialize(request,service_excepton)
+      @request = request
+      @exception = service_excepton
+      parse
+    end
+
+    def parse
+      if @request.format=="xml"
+        error = DomainTools::ErrorParser.from_xml(@request.content)
+      else
+        error = DomainTools::ErrorParser.from_json(@request.content)
+      end
+      @code, @message = error["code"], error["message"]                
+    end     
+    
+    def to_s
+      "[#{@code}] #{@message}"
+    end
+    
+    def code
+      @code
+    end
+    
+    def message
+      @message
+    end
+    
+    def request
+      @request
+    end
+    
+    def exception
+      @exception
+    end
+    
+  end
+end

data/lib/domain_tools/error_parser.rb

@@ -0,0 +1,19 @@
+module DomainTools
+  class ErrorParser
+    
+    def self.default_error
+      {:code => 0, :message => "Unknown error message"}
+    end
+    
+    def self.from_json(source)                  
+      hash = JSONParser::parse(source)
+      hash["error"]
+    end
+
+    def self.from_xml(source)
+      hash = XMLParser::parse(source)
+      hash["error"]
+    end
+    
+  end
+end

data/lib/domain_tools/exceptions.rb

@@ -0,0 +1,34 @@
+module DomainTools
+  module Exceptions
+    
+    class ServiceException                < StandardError;    end  
+    class NoSettingsException             < ServiceException; end
+    class NoCredentialsException          < ServiceException; end
+    class BadRequestException             < ServiceException; end
+    class NotAuthorizedException          < ServiceException; end
+    class NotFoundException               < ServiceException; end
+    class InternalServerErrorException    < ServiceException; end
+    class ServiceUnavailableException     < ServiceException; end  
+    class WrongParmatersException         < ServiceException; end
+    class NoDomainException               < ServiceException; end
+    class UnknownException                < ServiceException; end
+  
+    def self.raise_by_code(code)
+      case code.to_i          
+        when 400 
+          raise DomainTools::BadRequestException
+        when 401, 403
+          raise DomainTools::NotAuthorizedException      
+        when 404 
+          raise DomainTools::NotFoundException
+        when 500 
+          raise DomainTools::InternalServerErrorException
+        when 503 
+          raise DomainTools::ServiceUnavailableException
+        else 
+          raise DomainTools::UnknownException
+      end
+    end
+    
+  end                          
+end

data/lib/domain_tools/json_parser.rb

@@ -0,0 +1,10 @@
+module DomainTools
+  class JSONParser          
+                  
+    def self.parse(source)
+      require('json')
+      JSON.parse(source)
+    end
+    
+  end
+end

data/lib/domain_tools/request.rb

@@ -0,0 +1,173 @@
+module DomainTools
+  class Request
+    attr_accessor :domain, :format, :service, :parameters
+
+    def initialize(data)
+      data.each{|key, value| set_data(key,value)}
+    end
+    
+    def sign(active)
+      @signed = active
+    end
+    
+    def done?
+      return @done
+    end
+    
+    def error?
+      return !@error.nil?
+    end
+    
+    def success?
+      return @error.nil? && @http && @http.body    
+    end
+                                                
+    def [](key)
+      self.do unless done? 
+      @response[key]
+    end
+    
+    # build service url
+    def build_url                 
+      parts = []
+      uri   = ""
+      parts << "/#{@version}"         if @version
+      parts << "/#{@domain}"          if @domain
+      parts << "/#{@service}"         if @service
+      uri   =  parts.join("")
+      parts << "?"
+      parts << "format=#{@format}"
+      parts << "&#{authentication_params(uri)}"
+      parts << "#{format_parameters}" if @parameters
+      @url = parts.join("")
+    end
+    
+    def authentication_params(uri)                                      
+      return "&api_username=#{@username}&api_key=#{@key}" unless @signed
+      timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      data      = @username+timestamp+uri                                             
+      require 'openssl'
+      digester  = OpenSSL::Digest::Digest.new(DomainTools::DIGEST)
+      signature = OpenSSL::HMAC.hexdigest(digester, @key, data)
+      ["api_username=#{@username}","signature=#{signature}","timestamp=#{timestamp}"].join("&")
+    end
+    
+    
+    def validate
+      raise DomainTools::NoDomainException unless @domain || @parameters
+      raise DomainTools::NoCredentialsException unless @username || @key
+      # must be a valid format (will be default FORMAT constant if empty or wrong)
+      @format       = DomainTools::FORMAT     if @format!="json" && @format!="xml" && @format != "html"
+      # if not already defined, use default
+      @host         = DomainTools::HOST       if @host.nil?
+      @port         = DomainTools::PORT       if @port.nil?  
+      @signed       = DomainTools::SIGNED     if @signed.nil?
+      @version      = DomainTools::VERSION    if @version.nil?
+    end
+    
+    def do
+      execute
+    end      
+    
+    def do!
+      execute(true)
+    end
+    
+    # Connect to the server and execute the request
+    def execute(refresh=false)
+      return @response if @response && !refresh       
+      validate     
+      build_url                         
+      @done = true
+      DomainTools.counter!
+      require 'net/http'
+      begin
+        Net::HTTP.start(@host) do |http|
+          req = Net::HTTP::Get.new(@url)          
+          @http = http.request(req)       
+          @success = validate_http_status     
+          return finalize
+        end
+      rescue DomainTools::ServiceException => e                               
+        @error = DomainTools::Error.new(self,e)
+        raise e.class.new(e)
+      end
+    end
+    
+    def response
+      self.do
+    end
+      
+    def error
+      @error ? @error : nil
+    end
+       
+    # Check HTTP request status and raise an exception if needed
+    def validate_http_status    
+      return true if @http.code.to_i == 200
+      DomainTools::Exceptions::raise_by_code(@http.code)
+    end   
+       
+    def finalize                           
+      @response = DomainTools::Response.new(self.clone)
+    end
+    
+    def content
+      @http ? @http.body : nil
+    end   
+
+    # Response aliases
+    
+    def to_s
+      return @response.to_s if @response
+      self.do.to_s
+    end   
+    
+    def to_hash
+      return @response.to_hash if @response
+      self.do.to_hash
+    end
+    
+    def to_json
+      return @response.to_json if @response
+      @format = "json"
+      self.do
+    end
+    
+    def to_json!
+      return @response.to_json! if @response
+      self.do.to_json!
+    end
+    
+    def to_xml
+      return @response.to_xml if @response
+      @format = "xml"
+      self.do
+    end     
+    
+    def to_xml!
+      return @response.to_xml! if @response
+      self.do.to_xml!
+    end
+    
+    def to_yaml
+      return @response.to_yaml if @response
+      nil
+    end
+    
+    private 
+    
+    def set_data(key,val)
+      eval("@#{key.to_s} = val")
+    end
+    
+    def format_parameters
+      string = ""
+      string = @parameters if @parameters.kind_of? String
+      string = DomainTools::Util.vars_hash_to_string(@parameters) if @parameters.kind_of? Hash
+      string = "&#{string}" unless string.start_with?('&')
+      string
+    end
+    
+  end
+end

data/lib/domain_tools/response.rb

@@ -0,0 +1,78 @@
+module DomainTools
+  class Response
+    
+    def initialize(request)
+      @request = request.clone
+    end                    
+    
+    def request
+      @request
+    end     
+    
+    def content
+      request.content
+    end      
+    
+    def response
+      self.do
+    end
+    
+    def do
+      self
+    end
+    
+    def to_s
+      request.content
+    end             
+    
+    def render
+      to_s
+    end
+    
+    def to_hash
+      @parsed_object = parse unless @parsed_object
+      @parsed_object
+    end
+                                                 
+    # Return XML with parsed object (no new request made)
+    def to_xml!
+      self.to_hash.to_xml({:root => 'whoisapi'})
+    end             
+
+    # Execute the same request and return an XML response with a NEW request    
+    def to_xml
+      request.clone.to_xml
+    end
+               
+    # Return JSON with parsed object (no new request made)
+    def to_json!
+      self.to_hash.to_json
+    end        
+
+    # Execute the same request and return a JSON response with a NEW request
+    def to_json
+      request.clone.to_json
+    end
+    
+    def to_yaml
+      @parsed_object = parse unless @parsed_object
+      @parsed_object.to_yaml
+    end        
+    
+    def [](key)
+      @parsed_object = parse unless @parsed_object
+      return @parsed_object[key.to_s] if  @parsed_object[key.to_s]
+      nil
+    end      
+    
+    private
+    
+    def parse
+      return XMLParser::parse(request.content)        if request.format == "xml"
+      return JSONParser::parse(request.content)       if request.format == "json"   
+      # If HTML, we will fallback and make a new json request, then parse it
+      return JSONParser::parse(self.to_json.content)  if request.format == "html"
+    end
+    
+  end
+end

data/lib/domain_tools/util.rb

@@ -0,0 +1,12 @@
+module DomainTools
+  class Util
+    
+    # convert a Hash into inline string for GET params
+    def self.vars_hash_to_string(hash)    
+      vars = Array.new
+      hash.each {|key, value| vars.push key.to_s+"="+value.to_s}
+      '&'+vars.join('&')
+    end
+    
+  end
+end

data/lib/domain_tools/xml_parser.rb

@@ -0,0 +1,31 @@
+module DomainTools
+  class XMLParser          
+    
+    def self.parse(source)
+      require 'rexml/document'
+      doc = REXML::Document.new(source)
+      root_node = doc.elements.first
+      data_node = root_node.elements.first
+      hash = self.parse_node({},data_node)
+    end  
+    
+    def self.parse_node(hash,node)
+      val = {}
+      if node.has_elements?
+        node.elements.each{|subnode| val = self.parse_node(val,subnode)}
+      else
+        val = node.text
+      end
+      if hash[node.name].kind_of?(Array)
+        hash[node.name] << val 
+      elsif !hash[node.name].nil?
+        tmp = hash[node.name]
+        hash[node.name] = [tmp,val]
+      else
+        hash[node.name] = val
+      end      
+      hash
+    end
+    
+  end
+end

data/lib/domain_tools.rb

@@ -0,0 +1,28 @@
+DOMAIN_TOOLS_BASE_PATH = File.dirname(__FILE__)
+
+module DomainTools
+
+  # Defaut HOST for the request
+  HOST      = "api.domaintools.com"
+  # Use Signed Authentication
+  SIGNED    = true              
+  # Digest method used for HMAC signature
+  DIGEST    = "sha256"
+  # Default PORT for the request
+  PORT      = "80"
+  # Default VERSION for the request
+  VERSION   = "v1"
+  # Default FORMAT for the request
+  FORMAT    = "json"
+  
+end
+
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/exceptions"   # Exceptions classes declaration
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/json_parser"  # JSON parser methods
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/xml_parser"   # XML parser methods
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/error"        # Error class
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/error_parser" # Response error parser (JSON/XML)
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/request"      # Request class
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/response"     # Response class
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/util"         # Tools lib
+require "#{DOMAIN_TOOLS_BASE_PATH}/domain_tools/core"         # Core methods

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: domain_tools
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- DomainTools, LLC
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-10-26 00:00:00 Z
+dependencies: []
+
+description: Ruby wrapper of the domaintools.com API, allowing you to easily request any service available on domaintools.com
+email: MemberServices@DomainTools.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/domain_tools/core.rb
+- lib/domain_tools/error.rb
+- lib/domain_tools/error_parser.rb
+- lib/domain_tools/exceptions.rb
+- lib/domain_tools/json_parser.rb
+- lib/domain_tools/request.rb
+- lib/domain_tools/response.rb
+- lib/domain_tools/util.rb
+- lib/domain_tools/xml_parser.rb
+- lib/domain_tools.rb
+- examples/1_prepare.rb
+- examples/2_response.rb
+- examples/3_browsing.rb
+- examples/4_error.rb
+- examples/5_complete.rb
+homepage: http://www.domaintools.com/api/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 19
+      segments: 
+      - 1
+      - 3
+      - 4
+      version: 1.3.4
+requirements: []
+
+rubyforge_project: domain_tools
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Ruby gem for requesting domaintools.com webservices
+test_files: []
+