module HTTP::RestClient::DSL

Client DSL, mostly inpired from Nestful and HTTP::Chainable APIs.

Public Instance Methods

accept(type) click to toggle source

Sets the client expected HTTP response media type

@param type [String] the full mime-type name. @return [Hash]

# File lib/http/rest_client/dsl.rb, line 64
def accept(type)
  headers(HTTP::Headers::ACCEPT => HTTP::MimeType.normalize(type))
end
content_type(type) click to toggle source

Sets the client expected HTTP request content type

@param type [String] the full mime-type name. @return [Hash]

# File lib/http/rest_client/dsl.rb, line 56
def content_type(type)
  headers(HTTP::Headers::CONTENT_TYPE => HTTP::MimeType.normalize(type))
end
endpoint(value = nil) click to toggle source

Defines the client endpoint. Inheritable-safe

@param value [String] the endpoint URI. @return [String]

# File lib/http/rest_client/dsl.rb, line 32
def endpoint(value = nil)
  @endpoint = value if value

  return @endpoint if @endpoint

  superclass.respond_to?(:endpoint) ? superclass.endpoint : nil
end
error_response?(response, _parsed_response) click to toggle source

Validate error response

Looks at the response code by default.

@param response [HTTP::Response] the server response @param _parsed_response [Object] the parsed server response

@return [TrueClass] if status code is not a successful standard value

# File lib/http/rest_client/dsl.rb, line 142
def error_response?(response, _parsed_response)
  !(200..299).cover?(response.code)
end
extract_error(response, _parsed_response) click to toggle source

Extracts the error message from the response

@param response [HTTP::Response] the server response @param _parsed_response [Object] the parsed server response

@return [String]

# File lib/http/rest_client/dsl.rb, line 130
def extract_error(response, _parsed_response)
  [response.status.to_s, response.body.to_str].reject(&:empty?).join(': ')
end
handle_response(response) click to toggle source

Response handler, raises an [HTTP::RestClient::ResponseError] on errors

@param response [HTTP::Response] object @return [Hash] on parsable responses, alternatively the raw response

# File lib/http/rest_client/dsl.rb, line 103
def handle_response(response)
  parsed = parse_response(response)

  return parsed unless error_response?(response, parsed)

  raise ResponseError.new(extract_error(response, parsed), parsed)
end
headers(header = nil) click to toggle source

Updates the client headers

@param header [Hash] a dictionary to assign as a header. @return [Hash]

# File lib/http/rest_client/dsl.rb, line 17
def headers(header = nil)
  if header.is_a?(Hash)
    @headers ||= {}
    @headers.merge!(header)
  end

  return @headers if @headers

  superclass.respond_to?(:headers) ? superclass.headers : nil
end
parse_response(response) click to toggle source

Will try to parse the response

Will return nothing on failure.

@param response [HTTP::Response] the server response

@return [Object] upon success

# File lib/http/rest_client/dsl.rb, line 118
def parse_response(response)
  response.parse
rescue HTTP::Error
  nil
end
path(value = nil) click to toggle source

Defines the client resource path. Inheritable-safe

@param value [String] the endpoint URI path. @return [String]

# File lib/http/rest_client/dsl.rb, line 44
def path(value = nil)
  @path = value if value

  return @path if @path

  superclass.respond_to?(:path) ? superclass.path : nil
end
request(verb, uri, options = {}) click to toggle source

Makes an HTTP request and returns a parsed response where possible

@param verb [String] the HTTP method. @param uri [URI] the HTTP URI. @param options [Hash] the params/json-payload/form to include. @return parsed response, can be a [String], a [Hash] or an [Array]

# File lib/http/rest_client/dsl.rb, line 94
def request(verb, uri, options = {})
  client = HTTP::Client.new(headers: headers)
  handle_response(client.request(verb, uri, options))
end
uri(*parts) click to toggle source

Extends the endpoint and path full URL with new parts

@param parts [String] a list of parts to extend the base URL. @return [URI]

# File lib/http/rest_client/dsl.rb, line 79
def uri(*parts)
  # If an absolute URI already
  return parts.first if parts.first.is_a?(URI) && parts.first.host

  joined = [url, *parts].map(&:to_s).reject(&:empty?) * '/'

  URI.parse(joined)
end
url() click to toggle source

Parses and returns the endpoint and path full URL

@return [URI]

# File lib/http/rest_client/dsl.rb, line 71
def url
  URI.parse(endpoint).join(path.to_s).to_s
end