soda-ruby 0.2.11 → 0.2.12

data/CHANGELOG.mkd

@@ -5,3 +5,6 @@
 0.2.6 - Code cleanup from @raykao
 0.2.7 - Removing dead code and an un-needed dependency
 0.2.8 - Removing the nesting limit on the JSON parser
+0.2.10 - Removing a nesting limit that we missed
+0.2.11 - We weren't properly handling an empty payload response
+0.2.12 - Added a global option to disable SSL checking from https://github.com/socrata/soda-ruby/pull/7

data/lib/soda/client.rb

@@ -1,5 +1,9 @@
 #!/usr/bin/env ruby
-# Just a simple wrapper for SODA 2.0
+#
+# A Ruby client to the RESTful Socrata Open Data API
+#
+# For more details, check out http://socrata.github.io/soda-ruby
+#
 
 require 'net/https'
 require 'uri'
@@ -9,22 +13,103 @@ require 'hashie'
 
 module SODA
   class Client
+    ##
+    #
+    # Creates a new SODA client.
+    #
+    # * +config+ - A hash of the options to initialize the client with
+    #
+    # == Config Options
+    #
+    # * +:domain+ - The domain you want to access
+    # * +:username+ - Your Socrata username (optional, only necessary for modifying data)
+    # * +:password+ - Your Socrata password (optional, only necessary for modifying data)
+    # * +:app_token+ - Your Socrata application token (register at http://dev.socrata.com/register)
+    # * +:ignore_ssl+ - Ignore ssl errors (defaults to false)
+    #
+    # Returns a SODA::Client instance.
+    #
+    # == Example
+    #
+    #   client = SODA::Client.new({ :domain => "data.agency.gov", :app_token => "CGxarwoQlgQSev4zyUh5aR5J3" })
+    #
     def initialize(config = {})
       @config = config.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
     end
 
+    ##
+    #
+    # Retrieve a resource via an HTTP GET request.
+    #
+    # * +resource+ - The resource identifier or path.
+    # * +params+ - A hash of the URL parameters you want to pass
+    #
+    # Returns a Hashie::Mash that you can interact with as a Hash if you want.
+    #
+    # == Example
+    #
+    #   response = client.get("644b-gaut", { :firstname => "OPRAH", :lastname => "WINFREY", "$limit" => 5 })
+    #
     def get(resource, params = {})
       connection(:get, resource, nil, params)
     end
 
+    ##
+    #
+    # Update a resource via an HTTP POST request.
+    #
+    # Requires an authenticated client (both +:username+ and +:password+ passed into the +options+ hash)
+    #
+    # * +resource+ - The resource identifier or path.
+    # * +body+ - The payload to POST. Will be converted to JSON (optional).
+    # * +params+ - A hash of the URL parameters you want to pass (optional).
+    #
+    # Returns a Hashie::Mash that you can interact with as a Hash if you want.
+    #
+    # == Example
+    #
+    #   response = client.post("644b-gaut", [{ :firstname => "OPRAH", :lastname => "WINFREY" }])
+    #
     def post(resource, body = nil, params = {})
       connection(:post, resource, body, params)
     end
 
+    ##
+    #
+    # Replaces a resource via an HTTP PUT request.
+    #
+    # Requires an authenticated client (both +:username+ and +:password+ passed into the +options+ hash)
+    #
+    # * +resource+ - The resource identifier or path.
+    # * +body+ - The payload to POST. Will be converted to JSON (optional).
+    # * +params+ - A hash of the URL parameters you want to pass (optional).
+    #
+    # Returns a Hashie::Mash that you can interact with as a Hash if you want.
+    #
+    # == Example
+    #
+    #   response = client.put("644b-gaut", [{ :firstname => "OPRAH", :lastname => "WINFREY" }])
+    #
     def put(resource, body = nil, params = {})
       connection(:put, resource, body, params)
     end
 
+    ##
+    #
+    # Deletes a resource via an HTTP DELETE request.
+    #
+    # Requires an authenticated client (both +:username+ and +:password+ passed into the +options+ hash)
+    #
+    # * +resource+ - The resource identifier or path.
+    # * +body+ - The payload to send with the DELETE. Will be converted to JSON (optional).
+    # * +params+ - A hash of the URL parameters you want to pass (optional).
+    #
+    # Returns a Hashie::Mash that you can interact with as a Hash if you want.
+    #
+    # == Example
+    #
+    #   response = client.delete("644b-gaut")
+    #
     def delete(resource, body = nil, params = {})
       connection(:delete, resource, body, params)
     end
@@ -35,11 +120,7 @@ module SODA
 
       # Create our request
       uri = URI.parse("https://#{@config[:domain]}#{resource}.json?#{query}")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = true
-      if @config[:ignore_ssl]
-        http.auth.ssl.verify_mode = openssl::ssl::verify_none
-      end
+      http = build_http_client(uri.host, uri.port)
 
       request = Net::HTTP::Post.new(uri.request_uri)
       request.add_field("X-App-Token", @config[:app_token])
@@ -107,8 +188,7 @@ module SODA
 
         uri = URI.parse("https://#{@config[:domain]}#{path}?#{query}")
 
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = true
+        http = build_http_client(uri.host, uri.port)
         request = eval("Net::HTTP::#{method.capitalize}").new(uri.request_uri)
         request.add_field("X-App-Token", @config[:app_token])
 
@@ -137,5 +217,14 @@ module SODA
         end
       end
 
+      def build_http_client(host, port)
+        http = Net::HTTP.new(host, port)
+        http.use_ssl = true
+        if @config[:ignore_ssl]
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+        http
+      end
+
   end
 end

data/lib/soda/version.rb

@@ -1,3 +1,3 @@
 module SODA
-  VERSION = "0.2.11"
+  VERSION = "0.2.12"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: soda-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.11
+  version: 0.2.12
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-18 00:00:00.000000000 Z
+date: 2014-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie