simple_api_client 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ae96344d08b465b56f54620eb75714d3e61a81e8
-  data.tar.gz: 3a0153a20f2d6ef263f159aa2a1e07e0ce0ed5b2
+  metadata.gz: dbaa7daaea726e1e71511f35cf5fc9496529b16d
+  data.tar.gz: 361842e92d99a384508af44552cec9c64265c196
 SHA512:
-  metadata.gz: 24f3de8ea72890c464e226bcf1135ee44c713d3ca634cca91da41b0a8938c7c56f98db599cc5e5f8978843fbc4e897a55375217ec3f39f200d5c1e05fb0b8c4c
-  data.tar.gz: a2873988e18cbd74008d26b9d85a86210072847996d82919e45f5ddbe066e12683645eb2265a95eb616ed119c71583930c75d5881dd835b27797361f723b99e5
+  metadata.gz: 17d035a89fcf28f82e5fb11cad80cd68459385e43ee32b6b3e2ba116270663e800809aaca4eeba811d147373d8d51394e2a5b5e666b74da4292cd472895537b5
+  data.tar.gz: 91e7f9f9506078ff332b3d1bc9413376904b906e5df2d4112cbc7ff3e1d848cec7c7aec96dd5de1176c6505d4bdc68b9c1f5f3224b10362bf26d3bb8d70500b2

data/README.md

@@ -18,28 +18,7 @@ Or install it yourself as:
 
 ## Usage
 
-
-
-```ruby
-require 'simple_api_client'
-
-class YourClientClass
-
-  include SimpleApiClient
-
-  #including SimpleApiClient gives you a base initialize method that accepts two parameters.
-  #param1: excepts a URI object (which is used to set the Scheme, Host, Port etc, of your api.
-  #param2: is an object that responses to a call method which needs to accept a hash of options.
-
-  #Define your own endpoints
-
-  def client_info(client_id, payload)
-    call(method: :get, uri: uri('/client_info')
-  end
-
-
-end
-```
+See: [simple_api_client.rb documentation](https://github.com/dvallance/simple_api_client/blob/master/lib/simple_api_client.rb).
 
 ## Contributing
 

data/lib/simple_api_client.rb

@@ -4,6 +4,88 @@ require 'simple_api_client/http_caller/net_http'
 require 'simple_api_client/http_caller/response'
 require 'active_support/core_ext/module/delegation'
 
+# This module provides some simple basic methods to help create an HTTP based
+# API client with minimum effort.
+#
+# If you have an HTTP based API endpoint that accepts and delivers its payloads
+# via JSON or XML this gem is designed to quickly create the calling client. It
+# does this by providing an #initialize method that handles setting your HTTP
+# servers HOST, PORT, and SCHEME. These are set with a URI object or a URI
+# parse-able string. This allows you to declare any endpoints paths relative to
+# the provided URI.
+#
+# The second part of the equation is the Http client that actually makes the
+# call to the server. One is provided in this gem, +HttpCaller::NetHttp+, which
+# is just a wrapper around rubys Net::HTTP client. If your looking for something
+# more performant you can use the +http_caller-curb+ gem which provides a
+# wrapper around Curb (Libcurl bindings for Ruby). The HttpCaller is simply a
+# class that implements a +#call+ method that accepts an options hash.
+#
+# ==HttpCallers
+#
+# +HttpCaller::NetHttp+ (provided with this gem) and +HttpCaller::Curb+
+# (requires the http_caller-curb gem) are both very simple wrappers around
+# existing HTTP clients and they both understand the following options.
+# * :method - [:get, :post, :put] allows the caller to determine the type of
+# call to perform.
+# * :uri - the *absolute* url address for the endpoint. There is a convienence
+# method #uri which will turn a relative path into the absolute path based on
+# the initial URI passed to the initializer.
+# * :payload - a :post or :put can accept a payload.
+# * :accept - tells the server what format the payload will be [:json (default)
+# or :xml].
+# * :content_type - if your server api can respond in :json or :xml you can tell
+# it which you prefer (:json is the default).
+#
+# The HttpCallers I've provided both wrap exceptions in a common format.
+# * Errno::ECONNREFUSED - if the server is unresponsive
+# * Errno::ECONNRESET - the remote host reset the connection request
+# * Errno::ETIMEDOUT - timed out
+#
+# You can of course roll your own HttpCaller and if thats the case you can
+# change up the option names and respond to anything you want.
+#
+# ==Usage
+# This simplest usage would be to include the *SimpleApiClient* module in your
+# intended client and provide some basic endpoints.
+#    require 'simple_api_client'
+#
+#    class MyApiClient
+#      include SimpleApiClient
+#
+#      def get_address(user_id)
+#        # note the use of the #uri method to create an absolute uri
+#        path = uri("/users/#{user_id}/address")
+#
+#        # call is delegated to the provided HttpCaller object.
+#        call(uri: path, method: :get)
+#      end
+#
+#      # a post example could look like this
+#      def post_address(user_id, payload)
+#        path = uri("/users/#{user_id}/address")
+#        call(uri: path, method: :post, payload: payload)
+#      end
+#    end
+#
+#    my_client = MyApiClient.new('https://myserver:7788', HttpCaller::NetHttp.new)
+#
+#    #result is an HttpCaller::Response object which has a response code and body.
+#    result = my_client.get_address(1)
+#
+#    puts result.code
+#    # => 200
+#
+#    puts result.body #server specific, but the request will ask for json by default.
+#    # =>  "{\"street address\":\"897 someroad\"}"
+#
+# The code behind the scenes is vary simple and there is just an un-enforced
+# contract between the client class and the provided HttpCaller class. Your
+# defined endpoints simply pass the options to the HttpCaller and expect it to
+# respond. In my provided code that response is an HttpCaller::Response object
+# but this can be anything you want if you provide your own.
+#
+# @author David Vallance
 module SimpleApiClient
 
   ARGUMENT_ERROR_MESSAGE_HOST_MISSING = 'First argument must be a URI object or a URI string that provides a host. (i.e //myhost or http://myhost). Note: Scheme defaults to http if not provided.'
@@ -13,6 +95,15 @@ module SimpleApiClient
   delegate :call, to: :@caller
   attr_reader :caller
 
+  # Provides an default initializer for your class along with validation
+  # checking on the accepted params. An ArgumentError will be raised if the
+  # parameters do not satisfy expectations.
+  #
+  # @param uri [URI::HTTP, String] a URI object or a URI parse-able string.
+  # @param api_caller [#call] an object that responds to a #call method.
+  # HttpCaller::NetHttp is provided with this simple_api_client gem. See gem
+  # [http_caller-curb] for an optional HttpCaller::Curb implimentation using
+  # curb.
   def initialize uri, api_caller
     @uri = URI(uri)
     raise ArgumentError.new(ARGUMENT_ERROR_MESSAGE_HOST_MISSING) if @uri.host.nil?

data/lib/simple_api_client/version.rb

@@ -1,3 +1,3 @@
 module SimpleApiClient
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/simple_api_client_spec.rb

@@ -53,3 +53,27 @@ describe TestClient do
   end
 
 end
+
+class TestClientWithOwnInitializer
+  include SimpleApiClient
+
+  attr_accessor :my_string
+
+  def initialize string
+    super('http://127.0.0.1:9393', TestCaller.new)
+    self.my_string = string
+  end
+
+end
+
+describe TestClientWithOwnInitializer do
+  it '#initializes properly' do
+    client = TestClientWithOwnInitializer.new('something')
+    client.scheme.must_equal 'http'
+    client.host.must_equal '127.0.0.1'
+    client.port.must_equal 9393
+    client.caller.class.must_equal TestCaller
+    client.my_string.must_equal 'something'
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_api_client
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Dave Vallance
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-10 00:00:00.000000000 Z
+date: 2014-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport