Class: Springcm::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/springcm-sdk/client.rb

Constant Summary collapse

DEFAULT_OPTIONS =

Default API client options

{
  # If true, the client will use a simple retry mechanism when connection
  # to the API server fails due to e.g. temporary Internet service outage.
  # The connection is re-attempted up to five times, delaying 2 ** n
  # seconds between attempts, where n is the number of previous attempts.
  retry_connection_failed: true
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data_center, client_id, client_secret, options = DEFAULT_OPTIONS) ⇒ Client

Returns a new instance of Client.

Parameters:

  • data_center (String) —

    Data center name, e.g. uatna11

  • client_id (String) —

    Your API client ID

  • client_secret (String) —

    Your API client secret


26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/springcm-sdk/client.rb', line 26

def initialize(data_center, client_id, client_secret, options=DEFAULT_OPTIONS)
  if !["na11", "uatna11", "eu11", "eu21", "na21", "us11"].include?(data_center)
    raise Springcm::ConnectionInfoError.new("Invalid data center '#{data_center.to_s}'")
  end

  @options = options
  @data_center = data_center
  @client_id = client_id
  @client_secret = client_secret
  @api_version = "201411"
  @auth_version = "201606"
  @access_token
end

Instance Attribute Details

#access_token ⇒ Object (readonly)

Returns the value of attribute access_token


20
21
22
 
# File 'lib/springcm-sdk/client.rb', line 20

def access_token
  @access_token
end

Instance Method Details

#account ⇒ Object 


84
85
86
87
88
89
 
# File 'lib/springcm-sdk/client.rb', line 84

def 
  if @account.nil?
    
  end
  @account
end

#auth_url ⇒ Object

Get the URL for authentication requests


217
218
219
 
# File 'lib/springcm-sdk/client.rb', line 217

def auth_url
  "https://auth#{auth_subdomain_suffix}.springcm.com/api/v#{@auth_version}/apiuser"
end

#authenticated? ⇒ Boolean

Check if client is successfully authenticated

Returns:

  • (Boolean) —

    Whether a valid, unexpired access token is held.


197
198
199
 
# File 'lib/springcm-sdk/client.rb', line 197

def authenticated?
  !!@access_token && @expiry > Time.now
end

#authorized_connection(*options) ⇒ Object 


221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/springcm-sdk/client.rb', line 221

def authorized_connection(*options)
  if !authenticated?
    connect!
  end

  Faraday.new(*options) do |conn|
    options = [{
      max: 10,
      interval: 1,
      interval_randomness: 0.5,
      backoff_factor: 2,
      retry_statuses: [401, 429],
      exceptions: [Springcm::AuthExpiredError, Springcm::RateLimitExceededError],
      retry_block: -> (env, options, retries, exception) {
        if exception.class == Springcm::AuthExpiredError
          connect!
          env.request_headers['Authorization'] = "bearer #{@access_token}"
        end
      }
    }]
    conn.request :retry, *options
    conn.use Springcm::Middleware::RateLimit
    conn.use Springcm::Middleware::AuthExpire
    conn.use Springcm::Middleware::RetryConnectionFailed if @options[:retry_connection_failed]
    conn.adapter :net_http
    conn.authorization('bearer', @access_token)
  end
end

#connect(safe = true) ⇒ Boolean

Connect to the configured SpringCM API service

Parameters:

  • safe (defaults to: true) —

    If truthy, connection failure does not raise an exception

Returns:

  • (Boolean) —

    Whether connection was successful


43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/springcm-sdk/client.rb', line 43

def connect(safe=true)
  conn = Faraday.new(url: auth_url) do |conn|
    conn.request :retry, retry_statuses: [429], exceptions: [Springcm::RateLimitExceededError]
    conn.use Springcm::Middleware::RateLimit
    conn.use Springcm::Middleware::RetryConnectionFailed if @options[:retry_connection_failed]
    conn.adapter :net_http
  end
  res = conn.post do |req|
    req.headers['Content-Type'] = 'application/json'
    req.body = {
      client_id: @client_id,
      client_secret: @client_secret
    }.to_json
  end
  if res.success?
    data = JSON.parse(res.body)
    @access_token = data.fetch("access_token")
    @expiry = Time.now + data.fetch("expires_in") - 300
  else
    @access_token = nil
    @expiry = nil
    raise Springcm::InvalidClientIdOrSecretError.new if !safe
    return false
  end
end

#connect! ⇒ Object

Shorthand for connecting unsafely


92
93
94
 
# File 'lib/springcm-sdk/client.rb', line 92

def connect!
  connect(false)
end

#document(path: nil, uid: nil) ⇒ Object 


139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/springcm-sdk/client.rb', line 139

def document(path: nil, uid: nil)
  if (path.nil? && uid.nil?) || (!path.nil? && !uid.nil?)
    raise ArgumentError.new("Specify exactly one of: path, uid")
  end
  conn = authorized_connection(url: object_api_url)
  res = conn.get do |req|
    if !path.nil?
      req.url "documents"
      req.params["path"] = path
    elsif !uid.nil?
      req.url "documents/#{uid}"
    end
    Document.resource_params.each { |key, value|
      req.params[key] = value
    }
  end
  if res.success?
    data = JSON.parse(res.body)
    return Document.new(data, self)
  else
    nil
  end
end

#download_api_url ⇒ Object

Get the URL for content download requests


212
213
214
 
# File 'lib/springcm-sdk/client.rb', line 212

def download_api_url
  "https://apidownload#{@data_center}.springcm.com/v#{@api_version}"
end

#folder(path: nil, uid: nil) ⇒ Object 


112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/springcm-sdk/client.rb', line 112

def folder(path: nil, uid: nil)
  if (path.nil? && uid.nil?) || (!path.nil? && !uid.nil?)
    raise ArgumentError.new("Specify exactly one of: path, uid")
  end
  if path == "/"
    return root_folder
  end
  conn = authorized_connection(url: object_api_url)
  res = conn.get do |req|
    if !path.nil?
      req.url "folders"
      req.params["path"] = path
    elsif !uid.nil?
      req.url "folders/#{uid}"
    end
    Folder.resource_params.each { |key, value|
      req.params[key] = value
    }
  end
  if res.success?
    data = JSON.parse(res.body)
    return Folder.new(data, self)
  else
    nil
  end
end

#get_account_info ⇒ Object 


69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/springcm-sdk/client.rb', line 69

def 
  conn = authorized_connection(url: object_api_url)
  res = conn.get do |req|
    req.headers["Content-Type"] = "application/json"
    req.url "accounts/current"
  end
  if res.success?
    data = JSON.parse(res.body)
    @account = Springcm::Account.new(data, self)
    true
  else
    false
  end
end

#groups(offset: 0, limit: 20) ⇒ Object 


163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/springcm-sdk/client.rb', line 163

def groups(offset: 0, limit: 20)
  Helpers.validate_offset_limit!(offset, limit)
  conn = authorized_connection(url: object_api_url)
  res = conn.get do |req|
    req.url "groups"
    req.params["offset"] = offset
    req.params["limit"] = limit
  end
  if res.success?
    data = JSON.parse(res.body)
    ResourceList.new(data, self, Group, self)
  else
    nil
  end
end

#object_api_url ⇒ Object

Get the URL for object API requests


202
203
204
 
# File 'lib/springcm-sdk/client.rb', line 202

def object_api_url
  "https://api#{@data_center}.springcm.com/v#{@api_version}"
end

#root_folder ⇒ Springcm::Folder

Retrieve the root folder in SpringCM

Returns:


98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/springcm-sdk/client.rb', line 98

def root_folder
  conn = authorized_connection(url: object_api_url)
  res = conn.get do |req|
    req.url "folders"
    req.params["systemfolder"] = "root"
  end
  if res.success?
    data = JSON.parse(res.body)
    return Folder.new(data, self)
  else
    nil
  end
end

#upload_api_url ⇒ Object

Get the URL for content upload API requests


207
208
209
 
# File 'lib/springcm-sdk/client.rb', line 207

def upload_api_url
  "https://apiupload#{@data_center}.springcm.com/v#{@api_version}"
end

#users(offset: 0, limit: 20) ⇒ Object 


179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/springcm-sdk/client.rb', line 179

def users(offset: 0, limit: 20)
  Helpers.validate_offset_limit!(offset, limit)
  conn = authorized_connection(url: object_api_url)
  res = conn.get do |req|
    req.url "users"
    req.params["offset"] = offset
    req.params["limit"] = limit
  end
  if res.success?
    data = JSON.parse(res.body)
    ResourceList.new(data, self, User, self)
  else
    nil
  end
end