module CouchRest::RestAPI

CouchRest RestAPI

The basic low-level interface for all REST requests to the database. Everything must pass through here before it is sent to the server.

Six types of REST requests are supported: get, put, post, delete, copy and head.

Requests that do not have a payload, get, delete and copy, accept the URI and options parameters, where as put and post both expect a document as the second parameter.

The API will try to intelegently split the options between the JSON parser and RestClient API.

The following options will be recognised as header options and automatically added to the header hash:

The following request options are supported:

Any other remaining options will be sent to the MultiJSON backend except for the :raw option.

When :raw is true in PUT and POST requests, no attempt will be made to convert the document payload to JSON. This is not normally necessary as IO and Tempfile objects will not be parsed anyway. The result of the request will always be parsed.

For all other requests, mainly GET, the :raw option will make no attempt to parse the result. This is useful for receiving files from the database.

Public Instance Methods

copy(uri, destination, options = {}) click to toggle source

Send a COPY request to the URI provided.

# File lib/couchrest/rest_api.rb, line 64
def copy(uri, destination, options = {})
  opts = options.nil? ? {} : options.dup
  # also copy headers!
  opts[:headers] = options[:headers].nil? ? {} : options[:headers].dup
  opts[:headers]['Destination'] = destination
  execute(uri, :copy, opts)
end
default_headers() click to toggle source

The default RestClient headers used in each request.

# File lib/couchrest/rest_api.rb, line 78
def default_headers
  {
    :content_type => :json,
    :accept       => :json
  }
end
delete(uri, options = {}) click to toggle source

Send a DELETE request.

# File lib/couchrest/rest_api.rb, line 59
def delete(uri, options = {})
  execute(uri, :delete, options)
end
get(uri, options = {}) click to toggle source

Send a GET request.

# File lib/couchrest/rest_api.rb, line 44
def get(uri, options = {})
  execute(uri, :get, options)
end
head(uri, options = {}) click to toggle source

Send a HEAD request.

# File lib/couchrest/rest_api.rb, line 73
def head(uri, options = {})
  execute(uri, :head, options)
end
post(uri, doc = nil, options = {}) click to toggle source

Send a POST request.

# File lib/couchrest/rest_api.rb, line 54
def post(uri, doc = nil, options = {})
  execute(uri, :post, options, doc)
end
put(uri, doc = nil, options = {}) click to toggle source

Send a PUT request.

# File lib/couchrest/rest_api.rb, line 49
def put(uri, doc = nil, options = {})
  execute(uri, :put, options, doc)
end

Private Instance Methods

execute(url, method, options = {}, payload = nil) click to toggle source

Perform the RestClient request by removing the parse specific options, ensuring the payload is prepared, and sending the request ready to parse the response.

# File lib/couchrest/rest_api.rb, line 89
def execute(url, method, options = {}, payload = nil)
  request, parser = prepare_and_split_options(url, method, options)
  # Prepare the payload if it is provided
  request[:payload] = payload_from_doc(payload, parser) if payload
  begin
    parse_response(RestClient::Request.execute(request), parser)
  rescue Exception => e
    if $DEBUG
      raise "Error while sending a #{method.to_s.upcase} request #{uri}\noptions: #{opts.inspect}\n#{e}"
    else
      raise e
    end
  end
end
header_option_keys() click to toggle source
# File lib/couchrest/rest_api.rb, line 161
def header_option_keys
  [ :content_type, :accept ]
end
parse_response(result, opts = {}) click to toggle source

Parse the response provided.

# File lib/couchrest/rest_api.rb, line 149
def parse_response(result, opts = {})
  opts = opts.update(:create_additions => true) if decode_json_objects
  (opts.delete(:raw) || opts.delete(:head)) ? result : MultiJson.decode(result, opts.update(:max_nesting => false))
end
payload_from_doc(doc, opts = {}) click to toggle source

Check if the provided doc is nil or special IO device or temp file. If not, encode it into a string.

The options supported are:

  • :raw TrueClass, if true the payload will not be altered.

# File lib/couchrest/rest_api.rb, line 140
def payload_from_doc(doc, opts = {})
  if (opts.delete(:raw) || doc.nil? || doc.is_a?(IO) || doc.is_a?(Tempfile))
    doc
  else
    MultiJson.encode(doc.respond_to?(:as_couch_json) ? doc.as_couch_json : doc)
  end
end
prepare_and_split_options(url, method, options) click to toggle source

Prepare two hashes, one for the request to the REST backend and a second for the JSON parser.

Returns an array of request and parser options.

# File lib/couchrest/rest_api.rb, line 109
def prepare_and_split_options(url, method, options)
  request = {
    :url => url,
    :method => method,
    :headers => default_headers.merge(options[:headers] || {})
  }
  parser = {
    :raw => false,
    :head => (method == :head)
  }
  # Split the options
  (options || {}).each do |k,v|
    k = k.to_sym
    next if k == :headers # already dealt with
    if restclient_option_keys.include?(k)
      request[k] = v
    elsif header_option_keys.include?(k)
      request[:headers][k] = v
    else
      parser[k] = v
    end
  end
  [request, parser]
end
restclient_option_keys() click to toggle source

An array of all the options that should be passed through to restclient. Anything not in this list will be passed to the JSON parser.

# File lib/couchrest/rest_api.rb, line 156
def restclient_option_keys
  [:method, :url, :payload, :headers, :timeout, :open_timeout,
    :verify_ssl, :ssl_client_cert, :ssl_client_key, :ssl_ca_file]
end