Module: APISmith::Client::InstanceMethods

Defined in:
lib/api_smith/client.rb

Overview

The most important part of the client functionality - namely, provides a set of tools and methods that make it possible to build API clients. This is where the bulk of the client work takes place.

Instance Method Summary collapse

Instance Method Details

#delete(path, options = {}) ⇒ Object

Given a path relative to the endpoint (or /), will perform a DELETE request.

If provided, will use a :transformer to convert the resultant data into a useable object. Also, in the case an object is nested, allows you to traverse an object.

Parameters:

  • path (String) —

    the relative path to the object, pre-normalisation

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

    the raw options to be passed to #request!

See Also:



78
79
80
 
# File 'lib/api_smith/client.rb', line 78

def delete(path, options = {})
  request! :delete, path, options, :query
end

#get(path, options = {}) ⇒ Object

Given a path relative to the endpoint (or /), will perform a GET request.

If provided, will use a :transformer to convert the resultant data into a useable object. Also, in the case an object is nested, allows you to traverse an object.

Parameters:

  • path (String) —

    the relative path to the object, pre-normalisation

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

    the raw options to be passed to #request!

See Also:



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

def get(path, options = {})
  request! :get, path, options, :query
end

#post(path, options = {}) ⇒ Object

Given a path relative to the endpoint (or /), will perform a POST request.

If provided, will use a :transformer to convert the resultant data into a useable object. Also, in the case an object is nested, allows you to traverse an object.

Parameters:

  • path (String) —

    the relative path to the object, pre-normalisation

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

    the raw options to be passed to #request!

See Also:



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

def post(path, options = {})
  request! :post, path, options, :query, :body
end

#put(path, options = {}) ⇒ Object

Given a path relative to the endpoint (or /), will perform a PUT request.

If provided, will use a :transformer to convert the resultant data into a useable object. Also, in the case an object is nested, allows you to traverse an object.

Parameters:

  • path (String) —

    the relative path to the object, pre-normalisation

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

    the raw options to be passed to #request!

See Also:



65
66
67
 
# File 'lib/api_smith/client.rb', line 65

def put(path, options = {})
  request! :put, path, options, :query, :body
end

#request!(method, path, options, *param_types) ⇒ Object

Performs a HTTP request using HTTParty, using a set of expanded options built up by the current client.

Parameters:

  • method (:get, :post, :put, :delete) —

    the http request method to use

  • path (String) —

    the request path, relative to either the endpoint or /.

  • options (Hash{Symbol => Object}) —

    the options for the given request.

  • param_types (Array<Symbol>) —

    the given parameter types (e.g. :body, :query) to add to the request

Options Hash (options):

  • :skip_endpoint (true, false) —

    If true, don’t expand the given path before processing.

  • :response_container (Array) —

    If present, it will traverse an array of objects to unpack

  • :extra_request (Hash) —

    Extra raw, request options to pass in to the request

  • :extra_body (Hash) —

    Any parameters to add to the request body

  • :extra_query (Hash) —

    Any parameters to add to the request query string

  • :transform (#call) —

    An object, invoked via #call, that takes the response and transformers it into a useable form.

Returns:

  • the response, defaults to the raw HTTParty::Response

See Also:

  • #path_for
  • #extract_response
  • #transform_response


102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/api_smith/client.rb', line 102

def request!(method, path, options, *param_types)
  # Merge in the default request options, e.g. those to be passed to HTTParty raw
  request_options = merged_options_for(:request, options)
  # Exapdn the path out into a full version when the endpoint is present.
  full_path = request_options[:skip_endpoint] ? path : path_for(path)
  # For each of the given param_types (e.g. :query, :body) will automatically
  # merge in the options for the current request.
  param_types.each do |type|
    request_options[type] = merged_options_for(type, options)
  end
  # Finally, use HTTParty to get the response
  response = self.class.send method, full_path, request_options
  # Pre-process the response to check for errors.
  check_response_errors response
  # Unpack the response using the :response_container option
  inner_response = extract_response path, response, options
  # Finally, apply any transformations
  transform_response inner_response, options
end