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:



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

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:



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

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:



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

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:



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

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


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

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 = instrument_request method, full_path, options do
    self.class.send method, full_path, request_options
  end
  # 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