Class: Sagamore::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/sagamore/client.rb,
lib/sagamore/client/body.rb,
lib/sagamore/client/errors.rb,
lib/sagamore/client/uri_ext.rb,
lib/sagamore/client/resource.rb,
lib/sagamore/client/response.rb,
lib/sagamore/client/collection.rb

Overview

The main point of interaction for the Sagamore Client library.

Client code must successfully authenticate with the API via the #auth method before calling any HTTP methods or the API will return authorization errors.

Provides direct access to the URI-oriented interface via the HTTP methods. Provides access to the URI-oriented interface via the #[] method.

Defined Under Namespace

Modules: Collection, URIExt Classes: AuthFailed, Body, BodyError, RequestFailed, Resource, Response

Constant Summary collapse

URI =

Alias for Addressable::URI

Addressable::URI
DEFAULT_PER_PAGE =

Default number of records per page when iterating over collection resources

20
DEFAULT_TIMEOUT =

Default request timeout in seconds

60
DEFAULT_CONNECT_TIMEOUT =

Default connection timeout in seconds

10

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_uri, opts = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • base_uri (String) —

    Base URI

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :debug (Boolean, String) —

    Pass true to debug to stdout. Pass a String to debug to given filename.

  • :insecure (Boolean) —

    Disable SSL certificate verification



45
46
47
48
 
# File 'lib/sagamore/client.rb', line 45

def initialize(base_uri, opts={})
  @base_uri = URI.parse(base_uri)
  configure_session(base_uri, opts)
end

Instance Attribute Details

#base_uri ⇒ Addressable::URI (readonly)

Returns The client’s base URI.

Returns:



39
40
41
 
# File 'lib/sagamore/client.rb', line 39

def base_uri
  @base_uri
end

Instance Method Details

#[](uri) ⇒ Resource

Returns a Resource for the given URI path.

Returns:



171
172
173
 
# File 'lib/sagamore/client.rb', line 171

def [](uri)
  Resource.new(self, uri)
end

#auth(opts = {}) ⇒ true

Passes the given credentials to the server, storing the session token on success.

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :username (String) —

    Sagamore username

  • :password (String) —

    Sagamore password

Returns:

  • (true)

Raises:

  • (AuthFailed) —

    If the credentials were invalid or the server returned an error



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/sagamore/client.rb', line 80

def auth(opts={})
  unless opts[:username] && opts[:password]
    raise "Must specify :username and :password"
  end
  body = URI.form_encode \
    :auth_key => opts[:username],
    :password => opts[:password]
  response = post '/auth/identity/callback', body,
    'Content-Type' => 'application/x-www-form-urlencoded'
  response.success? or raise AuthFailed, "Sagamore auth failed"
end

#count(uri) ⇒ Integer

Returns a count of subordinate resources of the given collection resource URI.

Parameters:

  • uri (#to_s)

Returns:

  • (Integer) —

    The subordinate resource count

Raises:



210
211
212
213
214
 
# File 'lib/sagamore/client.rb', line 210

def count(uri)
  uri = URI.parse(uri)
  uri.merge_query_values! 'page' => 1, 'per_page' => 1
  get!(uri)['total']
end

#debug=(debug) ⇒ String, Boolean

Set to true to enable debugging to STDOUT or a string to write to the file at that path.

Parameters:

  • debug (String, Boolean)

Returns:

  • (String, Boolean) —

    The debug argument



67
68
69
 
# File 'lib/sagamore/client.rb', line 67

def debug=(debug)
  session.enable_debug(debug == true ? nil : debug)
end

#delete(uri, headers = false) ⇒ Response

Performs a DELETE request against the given URI and returns the Response.

Returns:



126
 
# File 'lib/sagamore/client.rb', line 126

def delete(uri, headers=false); make_request(:delete, uri, headers); end

#delete!(uri, headers = false) ⇒ Response

Performs a DELETE request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



135
 
# File 'lib/sagamore/client.rb', line 135

def delete!(uri, headers=false); raise_on_fail delete(uri, headers); end

#each(uri) ⇒ Object

Iterates over each subordinate resource of the given collection resource URI and yields its representation to the given block.



195
196
197
198
199
200
201
 
# File 'lib/sagamore/client.rb', line 195

def each(uri)
  each_page(uri) do |page|
    page['results'].each do |result|
      yield result
    end
  end
end

#each_page(uri) ⇒ Object

Iterates over each page of subordinate resources of the given collection resource URI and yields the Response to the block.



178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/sagamore/client.rb', line 178

def each_page(uri)
  uri = URI.parse(uri)
  total_pages = nil
  page = 1
  uri.query_values = {'per_page' => DEFAULT_PER_PAGE}.merge(uri.query_values || {})
  while total_pages.nil? or page <= total_pages
    uri.merge_query_values! 'page' => page
    response = get!(uri)
    yield response
    total_pages ||= response['pages']
    page += 1
  end
end

#get(uri, headers = false) ⇒ Response

Performs a GET request against the given URI and returns the Response.

Returns:



111
 
# File 'lib/sagamore/client.rb', line 111

def get(uri, headers=false); make_request(:get, uri, headers); end

#get!(uri, headers = false) ⇒ Response

Performs a GET request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



120
 
# File 'lib/sagamore/client.rb', line 120

def get!(uri, headers=false); raise_on_fail get(uri, headers); end

#head(uri, headers = false) ⇒ Response

Performs a HEAD request against the given URI and returns the Response.

Returns:



96
 
# File 'lib/sagamore/client.rb', line 96

def head(uri, headers=false); make_request(:head, uri, headers); end

#head!(uri, headers = false) ⇒ Response

Performs a HEAD request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



105
 
# File 'lib/sagamore/client.rb', line 105

def head!(uri, headers=false); raise_on_fail head(uri, headers); end

#post(uri, body, headers = false) ⇒ Response

Performs a POST request against the given URI and returns the Response.

Returns:



156
 
# File 'lib/sagamore/client.rb', line 156

def post(uri, body, headers=false); make_request(:post, uri, headers, body); end

#post!(uri, body, headers = false) ⇒ Response

Performs a POST request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



165
 
# File 'lib/sagamore/client.rb', line 165

def post!(uri, body, headers=false); raise_on_fail post(uri, body, headers); end

#put(uri, body, headers = false) ⇒ Response

Performs a PUT request against the given URI and returns the Response.

Returns:



141
 
# File 'lib/sagamore/client.rb', line 141

def put(uri, body, headers=false); make_request(:put, uri, headers, body); end

#put!(uri, body, headers = false) ⇒ Response

Performs a PUT request against the given URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:



150
 
# File 'lib/sagamore/client.rb', line 150

def put!(uri, body, headers=false); raise_on_fail put(uri, body, headers); end

#session ⇒ Patron::Session

Returns the underlying Patron session

Returns:

  • (Patron::Session)

See Also:



56
57
58
 
# File 'lib/sagamore/client.rb', line 56

def session
  @session ||= Patron::Session.new
end