class ROM::HTTP::Dataset
Represents a specific HTTP
collection resource. This class can be subclassed in a specialized HTTP
adapter to provide its own response/request handlers or any other configuration that should differ from the defaults.
@api public
Constants
- PATH_SEPARATOR
Public Instance Methods
Return the dataset path
@example
Dataset.new(path: '/users').path # => '/users'
@return [String] the dataset path, with leading slash
@api public
# File lib/rom/http/dataset.rb, line 199 def absolute_path PATH_SEPARATOR + path end
Return a new dataset with merged request body parameters
@param [Hash] body_params the new request body parameters to add
@example
users = Dataset.new(body_params: { uid: 33 }) users.add_body_params(login: 'jdoe').body_params # => { uid: 33, :login => 'jdoe' }
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 370 def add_body_params(new_body_params) with_options(body_params: ::ROM::HTTP::Transformer[:deep_merge][body_params, new_body_params]) end
Return a new dataset with additional header
@param header [Symbol] the HTTP
header to add @param value [String] the header value
@example
users = Dataset.new(headers: { Accept: 'application/json' }) users.add_header(:'X-Api-Key', '1234').headers # => { :Accept => 'application/json', :'X-Api-Key' => '1234' }
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 235 def add_header(header, value) with_headers(headers.merge(header => value)) end
Return a new dataset with merged request query parameters
@param [Hash] query_params the new request query parameters to add
@example
users = Dataset.new(query_params: { uid: 33 }) users.add_query_params(login: 'jdoe').query_params # => { uid: 33, :login => 'jdoe' }
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 337 def add_query_params(new_query_params) with_options(query_params: ::ROM::HTTP::Transformer[:deep_merge][query_params, new_query_params]) end
Return a new dataset with a modified path
@param path [String] new path fragment
@example
users.append_path('profiles').path # => users/profiles
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 291 def append_path(append_path) with_path(join_path(options[:path], append_path)) end
Perform an delete over HTTP
Delete
@return [Array<Hash>]
@api public
# File lib/rom/http/dataset.rb, line 423 def delete with_options(request_method: :delete).response end
Return true if request method is set to :delete
@return [Boolean]
@api public
# File lib/rom/http/dataset.rb, line 173 def delete? request_method.equal?(:delete) end
Iterate over each response value
@yield [Hash] a dataset tuple
@return [Enumerator] if no block is given @return [Array<Hash>]
@api public
# File lib/rom/http/dataset.rb, line 383 def each(&block) return to_enum unless block_given? response.each(&block) end
Return true if request method is set to :get
@return [Boolean]
@api public
# File lib/rom/http/dataset.rb, line 146 def get? request_method.equal?(:get) end
Perform an insert over HTTP
Post
@param [Hash] attributes the attributes to insert
@return [Array<Hash>]
@api public
# File lib/rom/http/dataset.rb, line 396 def insert(attributes) with_options( request_method: :post, body_params: attributes ).response end
Return the dataset path
@example
Dataset.new(path: '/users').path # => 'users'
@return [String] the dataset path, without a leading slash
@api public
# File lib/rom/http/dataset.rb, line 186 def path join_path(base_path, super) end
Return true if request method is set to :post
@return [Boolean]
@api public
# File lib/rom/http/dataset.rb, line 155 def post? request_method.equal?(:post) end
Return true if request method is set to :put
@return [Boolean]
@api public
# File lib/rom/http/dataset.rb, line 164 def put? request_method.equal?(:put) end
Execute the current dataset
@return [Array<hash>]
@api public
# File lib/rom/http/dataset.rb, line 432 def response response_handler.call(request_handler.call(self), self) end
Perform an update over HTTP
Put
@param [Hash] attributes the attributes to update
@return [Array<Hash>]
@api public
# File lib/rom/http/dataset.rb, line 410 def update(attributes) with_options( request_method: :put, body_params: attributes ).response end
Return the dataset’s URI
@return [URI::HTTP]
@api public
# File lib/rom/http/dataset.rb, line 131 def uri uri = URI(join_path(super, path)) if query_params.any? uri.query = query_param_encoder.call(query_params) end uri end
Return a new dataset with a different base path
@param base_path [String] the new base request path
@example
users.with_base_path('/profiles').base_path # => 'profiles'
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 261 def with_base_path(base_path) with_options(base_path: base_path) end
Return a new dataset with replaced request body parameters
@param [Hash] body_params the new request body parameters
@example
users = Dataset.new(body_params: { uid: 33 }) users.with_body_params(login: 'jdoe').body_params # => { :login => 'jdoe' }
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 354 def with_body_params(body_params) with_options(body_params: body_params) end
Return a new dataset with given headers
@param headers [Hash] The new headers
@note this replaces the dataset’s currently configured headers.
To non-destructively add a new header, use `#add_header`
@example
users = Dataset.new(headers: { Accept: 'application/json' }) users.with_headers(:'X-Api-Key' => '1234').headers # => { :'X-Api-Key' => '1234' }
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 218 def with_headers(headers) with_options(headers: headers) end
Return a new dataset with additional options
@param opts [Hash] the new options to add
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 246 def with_options(opts) __new__(**options.merge(opts)) end
Return a new dataset with a different path
@param path [String] the new request path
@example
users.with_path('/profiles').path # => 'profiles'
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 276 def with_path(path) with_options(path: path) end
Return a new dataset with replaced request query parameters
@param [Hash] query_params the new request query parameters
@example
users = Dataset.new(query_params: { uid: 33 }) users.with_query_params(login: 'jdoe').query_params # => { :login => 'jdoe' }
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 321 def with_query_params(query_params) with_options(query_params: query_params) end
Return a new dataset with a different request method
@param [Symbol] request_method the new HTTP
verb
@example
users.request_method(:put)
@return [Dataset]
@api public
# File lib/rom/http/dataset.rb, line 305 def with_request_method(request_method) with_options(request_method: request_method) end
Private Instance Methods
@api private
# File lib/rom/http/dataset.rb, line 441 def __new__(*args, **kwargs, &block) self.class.new(*args, **kwargs, &block) end
@api private
# File lib/rom/http/dataset.rb, line 446 def join_path(*paths) paths.reject(&:empty?).join(PATH_SEPARATOR) end