class Transloadit::Request
Wraps requests to the Transloadit
API. Ensures all API requests return a parsed Transloadit::Response
, and abstracts away finding a lightly-used instance on startup.
Constants
- API_ENDPOINT
The default
Transloadit
API endpoint.- API_HEADERS
The default headers to send to the API.
- HMAC_ALGORITHM
The HMAC algorithm used for calculation request signatures.
Attributes
@return [String] the authentication secret to sign the request with
@return [String] the API endpoint for the request
Public Class Methods
Prepares a request against an endpoint URL, optionally with an encryption secret. If only a path is passed, the API will automatically determine the best server to use. If a full URL is given, the host provided will be used.
@param [String] url the API endpoint @param [String] secret an optional secret with which to sign the request
# File lib/transloadit/request.rb, line 36 def initialize(url, secret = nil) self.url = URI.parse(url.to_s) self.secret = secret end
Private Class Methods
Computes an HMAC digest from the key and message.
@param [String] key the secret key to sign with @param [String] message the message to sign @return [String] the signature of the message
# File lib/transloadit/request.rb, line 194 def self._hmac(key, message) OpenSSL::HMAC.hexdigest HMAC_ALGORITHM, key, message end
Public Instance Methods
Performs an HTTP DELETE to the request's URL. Takes an optional hash containing the form-encoded payload.
@param [Hash] payload the payload to form-encode along with the POST @return [Transloadit::Response] the response
# File lib/transloadit/request.rb, line 61 def delete(payload = {}) self.request! do options = {:payload => self.to_payload(payload)} self.api(options = options)[url.path].delete(API_HEADERS) end end
Performs an HTTP GET to the request's URL. Takes an optional hash of query params.
@param [Hash] params additional query parameters @return [Transloadit::Response] the response
# File lib/transloadit/request.rb, line 48 def get(params = {}) self.request! do self.api[url.path + self.to_query(params)].get(API_HEADERS) end end
@return [String] a human-readable version of the prepared Request
# File lib/transloadit/request.rb, line 97 def inspect self.url.to_s.inspect end
Performs an HTTP POST to the request's URL. Takes an optional hash containing the form-encoded payload.
@param [Hash] payload the payload to form-encode along with the POST @return [Transloadit::Response] the response
# File lib/transloadit/request.rb, line 75 def post(payload = {}) self.request! do self.api[url.path].post(self.to_payload(payload), API_HEADERS) end end
Performs an HTTP PUT to the request's URL. Takes an optional hash containing the form-encoded payload.
@param [Hash] payload the payload to form-encode along with the POST @return [Transloadit::Response] the response
# File lib/transloadit/request.rb, line 88 def put(payload = {}) self.request! do self.api[url.path].put(self.to_payload(payload), API_HEADERS) end end
Protected Instance Methods
Retrieves the current API endpoint. If the URL of the request contains a hostname, then the hostname is used as the base endpoint of the API. Otherwise uses the class-level API base.
@return [RestClient::Resource] the API endpoint for this instance
# File lib/transloadit/request.rb, line 112 def api(options = {}) @api ||= begin case self.url.host when String then RestClient::Resource.new(self.url.host, options = options) else RestClient::Resource.new(API_ENDPOINT.host, options = options) end end end
Wraps a request's results in a Transloadit::Response
, even if an exception is raised by RestClient.
# File lib/transloadit/request.rb, line 168 def request!(&request) Transloadit::Response.new request.call rescue RestClient::Exception => e Transloadit::Response.new e.response end
Computes the HMAC digest of the params hash, if a secret was given to the instance.
@param [String] params the JSON encoded payload to sign @return [String] the HMAC signature for the params
# File lib/transloadit/request.rb, line 181 def signature(params) self.class._hmac(self.secret, params) if self.secret.to_s.length > 0 end
Updates the POST payload passed to be compliant with the Transloadit
API spec. JSONifies the value for the params
key and signs the request with the instance's secret
if it exists.
@param [Hash] the payload to update @return [Hash] the Transloadit-compliant POST payload
# File lib/transloadit/request.rb, line 129 def to_payload(payload = nil) return {} if payload.nil? return {} if payload.respond_to?(:empty?) and payload.empty? # TODO: refactor this, don't update a hash that's not ours payload.update :params => MultiJson.dump(payload[:params]) payload.update :signature => self.signature(payload[:params]) payload.delete :signature if payload[:signature].nil? payload end
Updates the GET/DELETE params hash to be compliant with the Transloadit
API by URI escaping and encoding the params hash, and attaching a signature.
@param [Hash] params the params to encode @return [String] the URI-encoded and escaped query parameters
# File lib/transloadit/request.rb, line 148 def to_query(params = nil) return '' if params.nil? return '' if params.respond_to?(:empty?) and params.empty? escape = Regexp.new("[^#{URI::PATTERN::UNRESERVED}]") params_in_json = MultiJson.dump(params) uri_params = URI.escape(params_in_json, escape) params = { :params => uri_params, :signature => self.signature(params_in_json) } '?' + params.map {|k,v| "#{k}=#{v}" if v }.compact.join('&') end