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}".freeze
CONTENT_TYPE = 
"application/x-www-form-urlencoded".freeze
ACCEPT = 
"application/json, */*".freeze
DEFAULT_OPTIONS = 
{
  :raise_exceptions => false,
  :encode_post_body_as_json => 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.



110
111
112
113
114
115
116
117
 
# File 'lib/halcyon/client.rb', line 110

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



54
55
56
 
# File 'lib/halcyon/client.rb', line 54

def headers
  @headers
end

#options ⇒ Object

Options



55
56
57
 
# File 'lib/halcyon/client.rb', line 55

def options
  @options
end

#uri ⇒ Object

The server URI



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

def uri
  @uri
end

Instance Method Details

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

Performs a DELETE request on the URI specified.



157
158
159
160
 
# File 'lib/halcyon/client.rb', line 157

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

#encode_post_body_as_json!(setting = true) ⇒ Object

Sets the option to encode the POST body as application/json compatible.



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

def encode_post_body_as_json!(setting = true)
  if self.options[:encode_post_body_as_json] = setting
    set_content_type "application/json"
  else
    set_content_type "application/x-www-form-urlencoded"
  end
end

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

Performs a GET request on the URI specified.



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

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.



149
150
151
152
153
 
# File 'lib/halcyon/client.rb', line 149

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.



164
165
166
167
168
 
# File 'lib/halcyon/client.rb', line 164

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

Sets the option to raise exceptions when the response from the server is not a 200 response.



122
123
124
 
# File 'lib/halcyon/client.rb', line 122

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