Class: Springboard::Client

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

Overview

The main point of interaction for the Springboard 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 Classes: AuthFailed, Body, BodyError, RequestFailed, Resource, Response, URI

Constant Summary collapse

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

  • :token (String) —

    Springboard API Token



41
42
43
44
 
# File 'lib/springboard/client.rb', line 41

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

Instance Attribute Details

#base_uri ⇒ URI (readonly)

Returns The client’s base URI.

Returns:

  • (URI) —

    The client’s base URI



34
35
36
 
# File 'lib/springboard/client.rb', line 34

def base_uri
  @base_uri
end

Instance Method Details

#[](uri) ⇒ Resource

Returns a Resource for the given URI path.

Returns:



170
171
172
 
# File 'lib/springboard/client.rb', line 170

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

#auth(opts = {}) ⇒ true

Deprecated.

see #initialize.

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) —

    Springboard username

  • :password (String) —

    Springboard password

Returns:

  • (true)

Raises:

  • (AuthFailed) —

    If the credentials were invalid or the server returned an error



77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/springboard/client.rb', line 77

def auth(opts={})
  warn "[DEPRECATION] `auth` is deprecated. Please use `Springboard::Client.new '#{base_uri}', token: 'secret_token'` instead."

  unless opts[:username] && opts[:password]
    raise "Must specify :username and :password"
  end
  body = ::URI.encode_www_form \
    :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, "Springboard 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:



209
210
211
212
213
 
# File 'lib/springboard/client.rb', line 209

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



63
64
65
 
# File 'lib/springboard/client.rb', line 63

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:



125
 
# File 'lib/springboard/client.rb', line 125

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:



134
 
# File 'lib/springboard/client.rb', line 134

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.



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

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.



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

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:



110
 
# File 'lib/springboard/client.rb', line 110

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:



119
 
# File 'lib/springboard/client.rb', line 119

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:



95
 
# File 'lib/springboard/client.rb', line 95

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:



104
 
# File 'lib/springboard/client.rb', line 104

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:



155
 
# File 'lib/springboard/client.rb', line 155

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:



164
 
# File 'lib/springboard/client.rb', line 164

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:



140
 
# File 'lib/springboard/client.rb', line 140

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:



149
 
# File 'lib/springboard/client.rb', line 149

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:



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

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