Module: RightScale::CloudApi::Mixin::QueryApiPatterns::ClassMethods

Defined in:
lib/base/helpers/query_api_patterns.rb

Overview

Query API patterns help one to simulate the Query API type through the REST API

When the REST API is powerfull enough it is not easy to code it becaue one have to worry about the path, the URL parameters, the headers and the body, when in the QUERY API all you need to worry about are the URL parameters.

The patterns described below help you to build methods that will take a linear set of parameters (usially) a hash and put then into the proper positions into the URL, headers or body.

TODO :add an example that would compare REST vs QUERY calls

There are 2 ways to define a Query API pattern:

  1. Manager class level:

We could use this when we define a new cloud handler. I dont see any use case right now because we can implement all we need now using the second way and Wrappers.

  1. Manager instance level: this is where Wrappers come.

Examples:

# Add a QUERY methods pattern:

query_api_pattern 'MethodName', :verb, 'path', UnifiedParams+:params+:headers+:body+:options+:before+:after do |args|
  puts   args # where args is a Hash: { :verb, :path, :opts, :manager  }
  ...
  return args # where args is a Hash: { :verb, :path, :opts [, :manager] }
end

module MyCoolCloud
  class  ApiManager < CloudApi::ApiManager
    query_api_pattern 'ListBuckets', :get

    query_api_pattern 'PutObject',   :put, '{:Bucket}/{:Object}',
                                     :body    => Utils::MUST_BE_SET,
                                     :headers => { 'content-type' => ['application/octet-stream'] }
    ..
  end
end

module MyCoolCloud
  module API_DEFAULT
    def self.extended(base)
      base.query_api_pattern 'ListBuckets',      :get

      base.query_api_pattern 'ListMyCoolBucket', :get do |args|
        args[:path] = 'my-cool-bucket'
        args
      end

      base.query_api_pattern 'PutObject',   :put, '{:Bucket:}/{:Object:}',
                                            :body    => Utils::MUST_BE_SET,
                                            :headers => { 'content-type' => ['application/octet-stream'] }

      base.query_api_pattern 'UploadPartCopy', :put,'{:DestinationBucket}/{:DestinationObject}',
                                               :params  => { 'partNumber' => :PartNumber, 'uploadId'   => :UploadId },
                                               :headers => { 'x-amz-copy-source' => '{:SourceBucket}/{:SourceObject}' }
      ..
    end
  end
end

Use case examples:
s3.MethodName(UnifiedParams+:params+:headers+:body+:options+:path+:verb)

# List all buckets
s3.ListBuckets

# Put object binary
s3.PutObject({'Bucket' => 'xxx', 'Object => 'yyy'}, :body => 'Hahaha')

# UploadCopy
s3.UploadPartCopy( 'SourceBucket'      => 'xxx',
                   'SourceObject       => 'yyy',
                   'DestinationBucket' => 'aaa',
                   'DestinationObject' => 'bbb',
                   'PartNumber'        => 134,
                   'UploadId'          => '111111',
                   'foo_param'         => 'foo',
                   'bar_param'         => 'bar' )

API:

  • public

Instance Method Summary collapse

Instance Method Details

#query_api_pattern(method_name, verb, path = '', opts = {}, storage = nil, &block) ⇒ void

This method returns an undefined value.

Defines a new query pattern

TODO: :explain options, callbacks, etc

Examples:

# no example

Parameters:

  • The name of the new QUERY-like method;

  • The HTTP verb.

  • (defaults to: '')

    The path pattern.

  • (defaults to: {})

    A set of extra parameters.

Options Hash (opts):

  • :params (Hash) —

    Url parameters pattern.

  • :headers (Hash) —

    HTTP headers pattern.

  • :body (Hash) —

    HTTP request body pattern.

  • :before (Proc) —

    Before callback.

  • :after (Hash) —

    After callback.

  • :defaults (Hash) —

    A set of default variables.

  • :options (Hash) —

    A set of extra options.

API:

  • public



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/base/helpers/query_api_patterns.rb', line 168

def query_api_pattern(method_name, verb, path='', opts={}, storage=nil, &block)
  opts        = opts.dup
  method_name = method_name.to_s
  storage   ||= query_api_patterns
  before   = opts.delete(:before)
  after    = opts.delete(:after)    || block
  defaults = opts.delete(:defaults) || {}
  params   = opts.delete(:params)   || {}
  headers  = opts.delete(:headers)  || {}
  options  = opts.delete(:options)  || {}
  body     = opts.delete(:body)     || nil
  # Complain if there are any unused keys left.
  fail(Error.new("#{method_name.inspect} pattern: unsupported key(s): #{opts.keys.map{|k| k.inspect}.join(',')}")) if opts.any?
  # Store the new pattern.
  storage[method_name] = {
    :verb     => verb.to_s.downcase.to_sym,
    :path     => path.to_s,
    :before   => before,
    :after    => after,
    :defaults => defaults,
    :params   => params,
    :headers  => HTTPHeaders::new(headers),
    :options  => options,
    :body     => body }
end

#query_api_patterns ⇒ Array

The method returns a list of pattternd defined in the current class

Examples:

# no example

Returns:

  • The arrays of patterns.

API:

  • public



143
144
145
 
# File 'lib/base/helpers/query_api_patterns.rb', line 143

def query_api_patterns
  @query_api_patterns ||= {}
end