Module: HTTP::RestClient::DSL

Defined in:
lib/http/rest_client/dsl.rb

Overview

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

Instance Method Summary collapse

Instance Method Details

#accept(type) ⇒ Hash

Sets the client expected HTTP response media type

Parameters:

  • type (String) —

    the full mime-type name.

Returns:

  • (Hash) 


79
80
81
 
# File 'lib/http/rest_client/dsl.rb', line 79

def accept(type)
  headers(HTTP::Headers::ACCEPT => HTTP::MimeType.normalize(type))
end

#content_type(type) ⇒ Hash

Sets the client expected HTTP request content type

Parameters:

  • type (String) —

    the full mime-type name.

Returns:

  • (Hash) 


71
72
73
 
# File 'lib/http/rest_client/dsl.rb', line 71

def content_type(type)
  headers(HTTP::Headers::CONTENT_TYPE => HTTP::MimeType.normalize(type))
end

#endpoint(value = nil) ⇒ String

Defines the client endpoint. Inheritable-safe

Parameters:

  • value (String) (defaults to: nil) —

    the endpoint URI.

Returns:

  • (String) 


32
33
34
35
36
37
38
 
# 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) ⇒ TrueClass

Validate error response

Looks at the response code by default.

Parameters:

  • response (HTTP::Response) —

    the server response

  • _parsed_response (Object) —

    the parsed server response

Returns:

  • (TrueClass) —

    if status code is not a successful standard value



158
159
160
 
# File 'lib/http/rest_client/dsl.rb', line 158

def error_response?(response, _parsed_response)
  !(200..299).cover?(response.code)
end

#extract_error(response, _parsed_response) ⇒ String

Extracts the error message from the response

Parameters:

  • response (HTTP::Response) —

    the server response

  • _parsed_response (Object) —

    the parsed server response

Returns:

  • (String) 


146
147
148
 
# File 'lib/http/rest_client/dsl.rb', line 146

def extract_error(response, _parsed_response)
  [response.status.to_s, response.body.to_str].reject(&:empty?).join(': ')
end

#handle_response(response) ⇒ Hash

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

Parameters:

  • response (HTTP::Response) —

    object

Returns:

  • (Hash) —

    on parsable responses, alternatively the raw response

Raises:



119
120
121
122
123
124
125
 
# File 'lib/http/rest_client/dsl.rb', line 119

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) ⇒ Hash

Updates the client headers

Parameters:

  • header (Hash) (defaults to: nil) —

    a dictionary to assign as a header.

Returns:

  • (Hash) 


17
18
19
20
21
22
23
24
25
26
 
# 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) ⇒ Object

Will try to parse the response

Will return nothing on failure.

Parameters:

  • response (HTTP::Response) —

    the server response

Returns:

  • (Object) —

    upon success



134
135
136
137
138
 
# File 'lib/http/rest_client/dsl.rb', line 134

def parse_response(response)
  response.parse
rescue HTTP::Error
  nil
end

#path(value = nil) ⇒ String

Defines the client resource path. Inheritable-safe

Parameters:

  • value (String) (defaults to: nil) —

    the endpoint URI path.

Returns:

  • (String) 


44
45
46
47
48
49
50
 
# 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

#proxy(*value) ⇒ String

Defines the client proxy hosts. Inheritable-safe

Expects an array with host, port, username and password. The last two are optional.

Parameters:

  • value (String) —

    the endpoint URI path.

Returns:

  • (String) 


59
60
61
62
63
64
65
 
# File 'lib/http/rest_client/dsl.rb', line 59

def proxy(*value)
  @proxy = value if value && !value.empty?

  return @proxy if @proxy

  superclass.respond_to?(:proxy) ? superclass.proxy : nil
end

#request(verb, uri, options = {}) ⇒ Object

Makes an HTTP request and returns a parsed response where possible

Parameters:

  • verb (String) —

    the HTTP method.

  • uri (URI) —

    the HTTP URI.

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

    the params/json-payload/form to include.

Returns:

  • parsed response, can be a [String], a [Hash] or an [Array]



109
110
111
112
113
 
# File 'lib/http/rest_client/dsl.rb', line 109

def request(verb, uri, options = {})
  client = HTTP::Client.new(headers: headers)
  client = client.via(*proxy) if proxy
  handle_response(client.request(verb, uri, options))
end

#uri(*parts) ⇒ URI

Extends the endpoint and path full URL with new parts

Parameters:

  • parts (String) —

    a list of parts to extend the base URL.

Returns:

  • (URI) 


94
95
96
97
98
99
100
101
 
# File 'lib/http/rest_client/dsl.rb', line 94

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 ⇒ URI

Parses and returns the endpoint and path full URL

Returns:

  • (URI) 


86
87
88
 
# File 'lib/http/rest_client/dsl.rb', line 86

def url
  URI.parse(endpoint).join(path.to_s).to_s
end