Class: APICake::Base

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/apicake/base.rb

Overview

To create your API wrapper, make a class that inherit from this class.

This class includes the HTTParty module, and the only requirement, is that you call base_uri to define the base URI of the API.

Example

class Client < APICake::Base
base_uri: 'http://some.api.com/v3'
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_sym) ⇒ Object

Any undefined method call will be delegated to the #get method.

Example

This:

client = Client.new
client.path 'optional_sub_path', optional_param: value, optional_param: value

Is equivalent to this:

client.get 'path/optional_sub_path', optional_param: value, optional_param: value


57
58
59
 
# File 'lib/apicake/base.rb', line 57

def method_missing(method_sym, *)
  get("/#{method_sym}", *)
end

Instance Attribute Details

#last_payload ⇒ Object (readonly)

Holds the last Payload object that was obtained by the last call to #get, #get!, #get_csv or #save_csv

Example

client = Client.new
client.some_path, param: value
p client.last_payload
# => a Payload object


30
31
32
 
# File 'lib/apicake/base.rb', line 30

def last_payload
  @last_payload
end

#last_url ⇒ Object (readonly)

Holds the last URL that was downloaded by the last call to #get, #get!, #get_csv or #save_csv.

Example

client = Client.new
client.some_path, param: value
p client.last_url
# => "http://some.api.com/v3/some_path?param=value"


42
43
44
 
# File 'lib/apicake/base.rb', line 42

def last_url
  @last_url
end

Instance Method Details

#cache ⇒ Object

This is the Lightly cache object. You can access or modify cache settings with this object.

Example

client = Client.new
client.cache.life = 3600
client.cache.dir = './cache'
client.cache.disable
client.cache.enable


77
78
79
 
# File 'lib/apicake/base.rb', line 77

def cache
  @cache ||= Lightly.new
end

#csv_node(data) ⇒ Object

Determins which part of the data is best suited to be displayed as CSV.

  • If the response contains one or more arrays, the first array will be the CSV output
  • Otherwise, if the response was parsed to a ruby object, the response itself will be used as a single-row CSV output.

Override this if you want to have a different decision process.



223
224
225
226
 
# File 'lib/apicake/base.rb', line 223

def csv_node(data)
  arrays = data.keys.select { |key| data[key].is_a? Array }
  arrays.empty? ? [data] : data[arrays.first]
end

#default_params ⇒ Object

Override this method in order to merge parameters into the HTTParty get request.

Eexample

class Client < APICake::Base
base_uri: 'http://some.api.com/v3'

def initialize(user, pass)
  @user, @pass = user, pass
end

def default_params
  { basic_auth: { username: user, password: pass }
end
end

See Also:



126
127
128
 
# File 'lib/apicake/base.rb', line 126

def default_params
  {}
end

#default_query ⇒ Object

Override this method in order to merge parameters into the query string before each call.

Example

class Client < APICake::Base
base_uri: 'http://some.api.com/v3'

def initialize(api_key)
  @api_key = api_key
end

def default_query
  { api_key: @api_key }
end
end

client = Client.new 'secret'
client.some_path param: 'value'
p client.last_url
# => "http://some.api.com/v3/some_path?api_key=secret&param=value"


103
104
105
 
# File 'lib/apicake/base.rb', line 103

def default_query
  {}
end

#get(path, extra = nil, params = {}) ⇒ Object

Make a request or get it from cache, and return the parsed response.

This is the same as calling #get! and gettings its parsed_response value.

Normally, you should not have the need to use this method, since all unhandled method calls are handled by #method_missing and are delegated here.

Example

client = Client.new
client.get 'path/to/resource', param: value, param: value


144
145
146
 
# File 'lib/apicake/base.rb', line 144

def get(path, extra = nil, params = {})
  get!(path.clone, extra.clone, params.clone).parsed_response
end

#get!(path, extra = nil, params = {}) ⇒ Object

Make a request or get it from cache, and return the entire Payload object.



150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/apicake/base.rb', line 150

def get!(path, extra = nil, params = {})
  path, extra, params = normalize path, extra, params
  key = cache_key path, extra, params

  @last_payload = cache.get key do
    http_get path, params
  end

  @last_url = @last_payload.request.uri.to_s
  @last_payload
end

#get_csv ⇒ Object

This method uses #get! to download and parse the content. It then makes the best effort to convert the right part of the data to a CSV string.

You can override this method if you wish to provide a different behavior.

Raises:



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/apicake/base.rb', line 191

def get_csv(*)
  payload = get!(*)
  raise BadResponse, "#{payload.response.code} #{payload.response.msg}" if payload.response.code != '200'

  response = payload.parsed_response
  raise BadResponse, 'Cannot parse response' unless response.is_a? Hash

  data = csv_node response
  header = data.first.keys

  CSV.generate do |csv|
    csv << header
    data.each { |row| csv << row.values }
  end
end

#respond_to_missing? ⇒ Boolean

Any undefined method call can be handled by this class.

Returns:

  • (Boolean) 


62
63
64
 
# File 'lib/apicake/base.rb', line 62

def respond_to_missing?(*)
  true
end

#save(filename, path, params = {}) ⇒ Object

Save the response body to a file

Example

client = Client.new
client.save 'out.json', 'some/to/resource', param: value


179
180
181
182
 
# File 'lib/apicake/base.rb', line 179

def save(filename, path, params = {})
  payload = get! path, nil, params
  File.write filename, payload.response.body
end

#save_csv(file) ⇒ Object

Same as #save, only use the output of #get_csv instead of the response body.



209
210
211
 
# File 'lib/apicake/base.rb', line 209

def save_csv(file, *)
  File.write file, get_csv(*)
end

#url(path, extra = nil, params = {}) ⇒ Object

A shortcut to just get the constructed URL of the request. Note that this call will make the HTTP request (unless it is already cached).

If you have already made the request, you can use #last_url instead.



167
168
169
170
 
# File 'lib/apicake/base.rb', line 167

def url(path, extra = nil, params = {})
  get! path, extra, params
  last_url
end