Class: RightSignature::Connection

Inherits:
Object
  • Object
show all
Includes:
Account, Document, Template
Defined in:
lib/rightsignature/connection.rb

Direct Known Subclasses

RailsStyle

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Template

#generate_build_url, #prefill, #prepackage, #prepackage_and_send, #send_as_embedded_signers, #send_template, #template_details, #templates_list, #trash_template

Methods included from Helpers

#array_to_acceptable_names_hash

Methods included from Account

#add_user, #usage_report, #user_details

Methods included from Document

#document_details, #documents_batch_details, #documents_list, #extend_document_expiration, #generate_document_redirect_url, #get_document_signer_links_for, #send_document, #send_document_from_data, #send_document_from_file, #send_document_from_url, #send_reminder, #trash_document, #update_document_tags

Constructor Details

#initialize(creds = {}) ⇒ Connection

Creates new instance of RightSignature::Connection to make API calls

  • creds: Hash of credentials for API Token or OAuth. If both are specified, it uses API Token

    • Hash key for API Token:

      • :api_token

    • Hash keys for OAuth:

      • :consumer_key

      • :consumer_secret

      • :access_token

      • :access_secret

Example for Api Token:

@rs_connection = RightSignature::Connection.new(:api_token => "MYTOKEN")

Example for OAuth:

@rs_connection = RightSignature::Connection.new(:consumer_key => "ckey", :consumer_secret => "csecret", :access_token => "atoken", :access_secret => "asecret")



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/rightsignature/connection.rb', line 27

def initialize(creds={})
  @configuration = {}
  RightSignature::Connection.oauth_keys.each do |key|
    @configuration[key] = creds[key].to_s
  end

  RightSignature::Connection.api_token_keys.each do |key|
    @configuration[key] = creds[key].to_s
  end

  @token_connection = RightSignature::TokenConnection.new(*RightSignature::Connection.api_token_keys.map{|k| @configuration[k]})
  @oauth_connection = RightSignature::OauthConnection.new(@configuration)

  @configuration
end

Instance Attribute Details

#configuration ⇒ Object

Returns the value of attribute configuration.



7
8
9
 
# File 'lib/rightsignature/connection.rb', line 7

def configuration
  @configuration
end

#oauth_connection ⇒ Object

Returns the value of attribute oauth_connection.



8
9
10
 
# File 'lib/rightsignature/connection.rb', line 8

def oauth_connection
  @oauth_connection
end

#token_connection ⇒ Object

Returns the value of attribute token_connection.



9
10
11
 
# File 'lib/rightsignature/connection.rb', line 9

def token_connection
  @token_connection
end

Class Method Details

.api_token_keys ⇒ Object

:nodoc:



77
78
79
 
# File 'lib/rightsignature/connection.rb', line 77

def self.api_token_keys
  [:api_token].freeze
end

.oauth_keys ⇒ Object

:nodoc:



72
73
74
 
# File 'lib/rightsignature/connection.rb', line 72

def self.oauth_keys
  [:consumer_key, :consumer_secret, :access_token, :access_secret].freeze
end

Instance Method Details

#check_credentials ⇒ Object

Checks if credentials are set for either API Token or for OAuth



45
46
47
 
# File 'lib/rightsignature/connection.rb', line 45

def check_credentials
  raise "Please set load_configuration with #{RightSignature::Connection.api_token_keys.join(',')} or #{RightSignature::Connection.oauth_keys.join(',')}" unless has_api_token? || has_oauth_credentials?
end

#delete(url, headers = {}) ⇒ Object

DELETE request to server

Arguments:

url: Path of API call
url: Hash of HTTP headers to include

Example:

@rs_connection.delete("/api/users.xml", {"User-Agent" => "My Own"})



121
122
123
124
125
126
127
128
129
130
 
# File 'lib/rightsignature/connection.rb', line 121

def delete(url, headers={})
  if has_api_token?
    options = {}
    options[:headers] = headers

    parse_response(@token_connection.request(:delete, url, options))
  else
    parse_response(@oauth_connection.request(:delete, url, headers))
  end
end

#get(url, params = {}, headers = {}) ⇒ Object

GET request to server

Arguments:

url: Path of API call
params: Hash of URL parameters to include in request
url: Hash of HTTP headers to include

Example:

@rs_connection.get("/api/documents.xml", {:search => "my term"}, {"User-Agent" => "My Own"})



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/rightsignature/connection.rb', line 142

def get(url, params={}, headers={})
  check_credentials
  
  if has_api_token?
    options = {}
    options[:headers] = headers
    options[:query] = params
    parse_response(@token_connection.request(:get, url, options))
  else
    unless params.empty?
      url = "#{url}?#{params.sort.map{|param| URI.escape("#{param[0]}=#{param[1]}")}.join('&')}"
    end
    parse_response(@oauth_connection.request(:get, url, headers))
  end
end

#has_api_token? ⇒ Boolean

Checks if API Token credentials are set. Does not validate creds with server.

Returns:

  • (Boolean) 


51
52
53
54
55
56
57
58
 
# File 'lib/rightsignature/connection.rb', line 51

def has_api_token?
  return false if @configuration.nil?
  RightSignature::Connection.api_token_keys.each do |key|
    return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
  end

  return true
end

#has_oauth_credentials? ⇒ Boolean

Checks if OAuth credentials are set. Does not validate creds with server.

Returns:

  • (Boolean) 


62
63
64
65
66
67
68
69
 
# File 'lib/rightsignature/connection.rb', line 62

def has_oauth_credentials?
  return false if @configuration.nil?
  RightSignature::Connection.oauth_keys.each do |key| 
    return false if @configuration[key].nil? || @configuration[key].match(/^\s*$/)
  end

  return true
end

#parse_response(response) ⇒ Object

Attempts to parse response from a connection and return it as a hash. If response isn’t a success, an RightSignature::ResponseError is raised

Arguments:

url: Path of API call
url: Hash of HTTP headers to include

Example:

@rs_connection.delete("/api/users.xml", {"User-Agent" => "My Own"})



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/rightsignature/connection.rb', line 190

def parse_response(response)
  if response.is_a? Net::HTTPResponse
    unless response.is_a? Net::HTTPSuccess
      raise RightSignature::ResponseError.new(response)
    end

    MultiXml.parse(response.body)
  else
    unless response.success?
      raise RightSignature::ResponseError.new(response)
    end
    
    response.parsed_response
  end
end

#post(url, body = {}, headers = {}) ⇒ Object

POST request to server

Arguments:

url: Path of API call
url: Hash of HTTP headers to include

Example:

@rs_connection.post("/api/users.xml", {"User-Agent" => "My Own"})



167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/rightsignature/connection.rb', line 167

def post(url, body={}, headers={})
  check_credentials
  
  if has_api_token?
    options = {}
    options[:headers] = headers
    options[:body] = XmlFu.xml(body)
    parse_response(@token_connection.request(:post, url, options))
  else
    parse_response(@oauth_connection.request(:post, url, XmlFu.xml(body), headers))
  end
end

#put(url, body = {}, headers = {}) ⇒ Object

PUT request to server

Arguments:

url: Path of API call
body: XML body in hash format
url: Hash of HTTP headers to include

Example:

@rs_connection.put("/api/documents.xml", {:documents=> {}}, {"User-Agent" => "My Own"})



100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/rightsignature/connection.rb', line 100

def put(url, body={}, headers={})
  if has_api_token?
    options = {}
    options[:headers] = headers
    options[:body] = XmlFu.xml(body)
    
    parse_response(@token_connection.request(:put, url, options))
  else
    parse_response(@oauth_connection.request(:put, url, XmlFu.xml(body), headers))
  end
end

#site ⇒ Object

:nodoc:



82
83
84
85
86
87
88
 
# File 'lib/rightsignature/connection.rb', line 82

def site
  if has_api_token?
    RightSignature::TokenConnection.base_uri
  else
    @oauth_connection.oauth_consumer.site
  end
end