Class: Halcyon::Client

Inherits:
Object
  • Object
show all
Includes:
Exceptions
Defined in:
lib/halcyon/client.rb,
lib/halcyon/client/ssl.rb

Overview

Building Custom Clients

Once your Halcyon JSON Server App starts to take shape, it may be useful to begin to write tests on expected functionality, and then to implement API calls with a designated Client lib for your Ruby or Rails apps, etc. The Base class provides a standard implementation and several options for wrapping up functionality of your app from the server side into the client side so that you may begin to use response data.

Creating Your Client

Creating a simple client can be as simple as this:

class Simple < Halcyon::Client
  def greet(name)
    get("/hello/#{name}")
  end
end

The only thing simply may be actually using the Simple client you just created.

But to actually get in and use the library, one has to take full advantage of the HTTP request methods, get, post, put, and delete. These methods simply return the JSON-parsed data from the server, effectively returning a hash with two key values, status which contains the HTTP status code, and body which contains the body of the content returned which can be any number of objects, including, but not limited to Hash, Array, Numeric, Nil, Boolean, String, etc.

You are not limited to what your methods can call: they are arbitrarily and solely up to your whims and needs. It is simply a matter of good design and performance when it comes to structuring and implementing client actions which can be complex or simple series of requests to the server.

Constant Summary collapse

USER_AGENT = 
"JSON/#{JSON::VERSION} Compatible (en-US) Halcyon::Client/#{Halcyon.version}"
CONTENT_TYPE = 
'application/json'
DEFAULT_OPTIONS = 
{
  :raise_exceptions => false
}

Constants included from Exceptions

Exceptions::HTTP_STATUS_CODES

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(uri, headers = {}) ⇒ Client

Connecting to the Server

Creates a new Client object to allow for requests and responses from the specified server.

The uri param contains the URL to the actual server, and should be in the format: “localhost:3801” or “app.domain.com:3401/”

Server Connections

Connecting only occurs at the actual event that a request is performed, so there is no need to worry about closing connections or managing connections in general other than good object housecleaning. (Be nice to your Garbage Collector.)

Usage

You can either provide a block to perform all of your requests and processing inside of or you can simply accept the object in response and call your request methods off of the returned object.

Alternatively, you could do both.

An example of creating and using a Simple client:

class Simple < Halcyon::Client
  def greet(name)
    get("/hello/#{name}")
  end
end
Simple.new('http://localhost:3801') do |s|
  puts s.greet("Johnny").inspect
end

This should effectively call inspect on a response hash similar to this:

{:status => 200, :body => 'Hello Johnny'}

Alternatively, you could perform the same with the following:

s = Simple.new('http://localhost:3801')
puts s.greet("Johnny").inspect

This should generate the exact same outcome as the previous example, except that it is not executed in a block.

The differences are purely semantic and of personal taste.



106
107
108
109
110
111
112
113
 
# File 'lib/halcyon/client.rb', line 106

def initialize(uri, headers = {})
  self.uri = URI.parse(uri)
  self.headers = headers
  self.options = DEFAULT_OPTIONS
  if block_given?
    yield self
  end
end

Instance Attribute Details

#headers ⇒ Object

Instance-wide headers



51
52
53
 
# File 'lib/halcyon/client.rb', line 51

def headers
  @headers
end

#options ⇒ Object

Options



52
53
54
 
# File 'lib/halcyon/client.rb', line 52

def options
  @options
end

#uri ⇒ Object

The server URI



50
51
52
 
# File 'lib/halcyon/client.rb', line 50

def uri
  @uri
end

Instance Method Details

#delete(uri, headers = {}) ⇒ Object

Performs a DELETE request on the URI specified.



137
138
139
140
 
# File 'lib/halcyon/client.rb', line 137

def delete(uri, headers={})
  req = Net::HTTP::Delete.new(uri)
  request(req, headers)
end

#get(uri, headers = {}) ⇒ Object

Performs a GET request on the URI specified.



124
125
126
127
 
# File 'lib/halcyon/client.rb', line 124

def get(uri, headers={})
  req = Net::HTTP::Get.new(uri)
  request(req, headers)
end

#post(uri, data = {}, headers = {}) ⇒ Object

Performs a POST request on the URI specified.



130
131
132
133
134
 
# File 'lib/halcyon/client.rb', line 130

def post(uri, data = {}, headers={})
  req = Net::HTTP::Post.new(uri)
  req.body = format_body(data)
  request(req, headers)
end

#put(uri, data = {}, headers = {}) ⇒ Object

Performs a PUT request on the URI specified.



143
144
145
146
147
 
# File 'lib/halcyon/client.rb', line 143

def put(uri, data = {}, headers={})
  req = Net::HTTP::Put.new(uri)
  req.body = format_body(data)
  request(req, headers)
end

#raise_exceptions!(setting = true) ⇒ Object 



115
116
117
 
# File 'lib/halcyon/client.rb', line 115

def raise_exceptions!(setting = true)
  self.options[:raise_exceptions] = setting
end