Class: SoftLayer::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/softlayer/Client.rb

Overview

A client is responsible for storing authentication information for API calls and it serves as a central repository for the Service instances that call into the network API.

When you create a client, you pass in hash arguments specifying how the client should access the SoftLayer API.

The following symbols are the keys for options you pass to the constructor:

  • :username - a non-empty string providing the username to use for requests to the client

  • :api_key - a non-empty string providing the api key to use for requests to the client

  • :endpoint_url - a non-empty string providing the endpoint URL to use for requests to the client

If any of these are missing then the Client class will look to the SoftLayer::Config class to provide the missing information. Please see that class for details.

Constant Summary collapse

@@default_client =

The client class maintains an (optional) default client. The default client will be used by many methods if you do not provide an explicit client.

nil

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Clients are built with a number of settings:

  • :username - The username of the account you wish to access through the API

  • :api_key - The API key used to authenticate the user with the API

  • :endpoint_url - The API endpoint the client should connect to. This defaults to API_PUBLIC_ENDPOINT

  • :user_agent - A string that is passed along as the user agent when the client sends requests to the server

  • :timeout - An integer number of seconds to wait until network requests time out. Corresponds to the network_timeout property of the client

If these arguments are not provided then the client will try to locate them using other sources including global variables, and the SoftLayer config file (if one exists)



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/softlayer/Client.rb', line 99

def initialize(options = {})
  @services = { }

  settings = Config.client_settings(options)

  # pick up the username from the options, the global, or assume no username
  @username = settings[:username]

  # do a similar thing for the api key
  @api_key = settings[:api_key]

  # grab token pair
  @userId = settings[:userId]
  @authToken = settings[:authToken]

  # and the endpoint url
  @endpoint_url = settings[:endpoint_url] || API_PUBLIC_ENDPOINT

  # set the user agent to the one provided, or set it to a default one
  @user_agent = settings[:user_agent] || "softlayer_api gem/#{SoftLayer::VERSION} (Ruby #{RUBY_PLATFORM}/#{RUBY_VERSION})"

  # and assign a time out if the settings offer one
  @network_timeout = settings[:timeout] if settings.has_key?(:timeout)

  raise "A SoftLayer Client requires an endpoint URL" if !@endpoint_url || @endpoint_url.empty?
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

An API key passed as part of the authentication of each request. Cannot be empty or nil.



28
29
30
 
# File 'lib/softlayer/Client.rb', line 28

def api_key
  @api_key
end

#endpoint_url ⇒ Object (readonly)

The base URL for requests that are passed to the server. Cannot be empty or nil.



31
32
33
 
# File 'lib/softlayer/Client.rb', line 31

def endpoint_url
  @endpoint_url
end

#network_timeout ⇒ Object (readonly)

An integer value (in seconds). The number of seconds to wait for HTTP requests to the network API until they timeout. This value can be nil in which case the timeout will be the default value for the library handling network communication (often 30 seconds)



39
40
41
 
# File 'lib/softlayer/Client.rb', line 39

def network_timeout
  @network_timeout
end

#user_agent ⇒ Object

A string passed as the value for the User-Agent header when requests are sent to SoftLayer API.



34
35
36
 
# File 'lib/softlayer/Client.rb', line 34

def user_agent
  @user_agent
end

#username ⇒ Object (readonly)

A username passed as authentication for each request. Cannot be empty or nil.



25
26
27
 
# File 'lib/softlayer/Client.rb', line 25

def username
  @username
end

Class Method Details

.default_client ⇒ Object

:attr_accessor: The client class can maintain a single instance of Client as the “default client” Other parts of the library that accept a client as part of their calling sequence will look for the default client if one is not provided in the call

This routine returns the client set as the default client. It can be nil



53
54
55
 
# File 'lib/softlayer/Client.rb', line 53

def self.default_client
  return @@default_client
end

.default_client=(new_default) ⇒ Object 



57
58
59
 
# File 'lib/softlayer/Client.rb', line 57

def self.default_client=(new_default)
  @@default_client = new_default
end

.with_password(options = {}) ⇒ Object

This will be using your username and password to get a portal token with which to authenticate client calls. This is a wrapper around Client.new. You can pass it the same parameters as with Client.new, with the exception that this will be expecting a password in the options hash.



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/softlayer/Client.rb', line 67

def self.with_password(options = {})
  if options[:username].nil? || options[:username].empty?
    raise 'A username is required to create this client'
  end

  if options[:password].nil? || options[:password].empty?
    raise 'A password is required to create this client'
  end

  service = SoftLayer::Service.new('SoftLayer_User_Customer')
  token = service.getPortalLoginToken(
    options[:username], options[:password]
  )

  options[:userId] = token['userId']
  options[:authToken] = token['hash']

  SoftLayer::Client.new(options)
end

Instance Method Details

#[](service_name) ⇒ Object 



190
191
192
 
# File 'lib/softlayer/Client.rb', line 190

def [](service_name)
  service_named(service_name)
end

#authentication_headers ⇒ Object

return a hash of the authentication headers for the client



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/softlayer/Client.rb', line 137

def authentication_headers
  if token_based?
    {
      'authenticate' => {
        'complexType' => 'PortalLoginToken',
        'userId' => @userId,
        'authToken' => @authToken
      }
    }
  elsif key_based?
    {
      'authenticate' => {
        'username' => @username,
        'apiKey' => @api_key
      }
    }
  else
    {}
  end
end

#key_based? ⇒ Boolean

return whether this client is using api_key-based authentication

Returns:

  • (Boolean) 


132
133
134
 
# File 'lib/softlayer/Client.rb', line 132

def key_based?
  @username && !@username.empty? && @api_key && !@api_key.empty?
end

#service_named(service_name, service_options = {}) ⇒ Object

Returns a service with the given name.

If a service has already been created by this client that same service will be returned each time it is called for by name. Otherwise the system will try to construct a new service object and return that.

If the service has to be created then the service_options will be passed along to the creative function. However, when returning a previously created Service, the service_options will be ignored.

If the service_name provided does not start with ‘SoftLayer_’ that prefix will be added

Raises:

  • (ArgumentError) 


170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/softlayer/Client.rb', line 170

def service_named(service_name, service_options = {})
  raise ArgumentError,"Please provide a service name" if service_name.nil? || service_name.empty?

  # Strip whitespace from service_name and ensure that it starts with "SoftLayer_".
  # If it does not, then add the prefix.
  full_name = service_name.to_s.strip
  if not full_name =~ /\ASoftLayer_/
    full_name = "SoftLayer_#{service_name}"
  end

  # if we've already created this service, just return it
  # otherwise create a new service
  service_key = full_name.to_sym
  if !@services.has_key?(service_key)
    @services[service_key] = SoftLayer::Service.new(full_name, {:client => self}.merge(service_options))
  end

  @services[service_key]
end

#token_based? ⇒ Boolean

return whether this client is using token-based authentication

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/softlayer/Client.rb', line 127

def token_based?
  @userId && @authToken && !@authToken.empty?
end