Class: Springboard::Client::Resource

Inherits:
Object
  • Object
show all
Includes:
Collection
Defined in:
lib/springboard/client/resource.rb

Overview

An representation of an API resource identified by a URI. Allows triggering API calls via HTTP methods. Allows constructing new resources in a chained style by calling the methods that manipulate the URI and return a new resource.

Resources are usually constructed via the Client#[] method.

Examples:

Chaining

new_resource = resource.
  filter(:field => 'value').
  sort(:id).
  embed(:related_resource)

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Collection

#count, #each, #each_page, #empty?, #filter, #first, #only, #sort, #while_results

Constructor Details

#initialize(client, uri_or_path) ⇒ Resource

Returns a new instance of Resource

Parameters:


34
35
36
37
# File 'lib/springboard/client/resource.rb', line 34

def initialize(client, uri_or_path)
  @client = client
  @uri = normalize_uri(uri_or_path)
end

Instance Attribute Details

#clientClient (readonly)

The underlying Springboard Client.

Returns:


29
30
31
# File 'lib/springboard/client/resource.rb', line 29

def client
  @client
end

#uriAddressable::URI (readonly)

The resource's URI.

Returns:

  • (Addressable::URI)

23
24
25
# File 'lib/springboard/client/resource.rb', line 23

def uri
  @uri
end

Instance Method Details

#[](uri) ⇒ Resource

Returns a new subordinate resource with the given sub-path.

Returns:


118
119
120
# File 'lib/springboard/client/resource.rb', line 118

def [](uri)
  clone(self.uri.subpath(uri))
end

#clone(uri = nil) ⇒ Resource

Returns a cloned copy of the resource with the same URI.

Returns:


164
165
166
# File 'lib/springboard/client/resource.rb', line 164

def clone(uri=nil)
  self.class.new(client, uri ? uri : self.uri)
end

#delete(headers = false) ⇒ Response

Performs a DELETE request against the resource's URI and returns the Response.

Returns:


73
# File 'lib/springboard/client/resource.rb', line 73

def delete(headers=false); call_client(:delete, headers); end

#delete!(headers = false) ⇒ Response

Performs a DELETE request against the resource's URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:


82
# File 'lib/springboard/client/resource.rb', line 82

def delete!(headers=false); call_client(:delete!, headers); end

#embed(*embeds) ⇒ Resource

Returns a new resource with the given embeds added to the query string (via _include params).

Returns:


173
174
175
176
# File 'lib/springboard/client/resource.rb', line 173

def embed(*embeds)
  embeds = (query['_include'] || []) + embeds
  query('_include' => embeds)
end

#exists?Boolean

Returns true if a HEAD request to the resource returns a successful response, false if it returns 404, otherwise raises an exception.

Returns:

  • (Boolean)

Raises:


185
186
187
188
189
190
191
192
# File 'lib/springboard/client/resource.rb', line 185

def exists?
  response = head
  return true if response.success?
  return false if response.status == 404
  error = RequestFailed.new "Request during call to 'exists?' resulted in non-404 error."
  error.response = response
  raise error
end

#get(headers = false) ⇒ Response

Performs a GET request against the resource's URI and returns the Response.

Returns:


58
# File 'lib/springboard/client/resource.rb', line 58

def get(headers=false); call_client(:get, headers); end

#get!(headers = false) ⇒ Response

Performs a GET request against the resource's URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:


67
# File 'lib/springboard/client/resource.rb', line 67

def get!(headers=false); call_client(:get!, headers); end

#head(headers = false) ⇒ Response

Performs a HEAD request against the resource's URI and returns the Response.

Returns:


43
# File 'lib/springboard/client/resource.rb', line 43

def head(headers=false); call_client(:head, headers); end

#head!(headers = false) ⇒ Response

Performs a HEAD request against the resource's URI. Returns the Response on success and raises a RequestFailed on failure..

Returns:

Raises:


52
# File 'lib/springboard/client/resource.rb', line 52

def head!(headers=false); call_client(:head!, headers); end

#post(body, headers = false) ⇒ Response

Performs a POST request against the resource's URI and returns the Response.

Returns:


103
# File 'lib/springboard/client/resource.rb', line 103

def post(body, headers=false); call_client(:post, body, headers); end

#post!(body, headers = false) ⇒ Response

Performs a POST request against the resource's URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:


112
# File 'lib/springboard/client/resource.rb', line 112

def post!(body, headers=false); call_client(:post!, body, headers); end

#put(body, headers = false) ⇒ Response

Performs a PUT request against the resource's URI and returns the Response.

Returns:


88
# File 'lib/springboard/client/resource.rb', line 88

def put(body, headers=false); call_client(:put, body, headers); end

#put!(body, headers = false) ⇒ Response

Performs a PUT request against the resource's URI. Returns the Response on success and raises a RequestFailed on failure.

Returns:

Raises:


97
# File 'lib/springboard/client/resource.rb', line 97

def put!(body, headers=false); call_client(:put!, body, headers); end

#query(params) ⇒ Resource #queryHash Also known as: params

Overloads:

  • #query(params) ⇒ Resource

    Returns a new resource where the given params hash of parameter names and values is merged with the existing query string parameters.

    Parameters:

    • params (Hash)

      New query string parameters

    Returns:

  • #queryHash

    Returns the resource's current query string parameters and values as a hash.

    Returns:

    • (Hash)

148
149
150
151
152
153
154
155
156
# File 'lib/springboard/client/resource.rb', line 148

def query(params=nil)
  if params
    uri = self.uri.dup
    uri.merge_query_values!(params)
    clone(uri)
  else
    self.uri.query_values || {}
  end
end