Class: Bitly::API::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/bitly/api/client.rb

Overview

The class that all the API requests are made through. The Bitly::API::Client is authorized with an OAuth token and takes care of setting the correct path, parameters and headers when making requests to the API.

This class will be used the most and includes short cut methods to request the popular objects in the system.

Constant Summary collapse

USER_AGENT = 
"Ruby Bitly/#{Bitly::VERSION}"

Instance Method Summary collapse

Constructor Details

#initialize(http: Bitly::HTTP::Client.new, token:) ⇒ Bitly::API::Client

Creates a new Bitly::API::Client, authorized with an OAuth token and with an optional HTTP client.

Examples:

client = Bitly::API::Client.new(token: oauth_token)



31
32
33
34
 
# File 'lib/bitly/api/client.rb', line 31

def initialize(http: Bitly::HTTP::Client.new, token:)
  @http = http
  @token = token
end

Instance Method Details

Return information about a bitlink [‘GET /v4/bitlink/#bitlink`](dev.bitly.com/api-reference/#getBitlink)

Examples:

bitlink = client.bitlink(bitlink: "bit.ly/example")



107
108
109
 
# File 'lib/bitly/api/client.rb', line 107

def bitlink(bitlink:)
  Bitlink.fetch(client: self, bitlink: bitlink)
end

#bitlink_clicks(bitlink:, unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Bitly::API::Bitlink::LinkClick::List

Get the clicks for a bitlink. [‘GET /v4/bitlink/#bitlink/clicks`](dev.bitly.com/api-reference/#getClicksForBitlink)



243
244
245
246
247
248
249
250
251
252
 
# File 'lib/bitly/api/client.rb', line 243

def bitlink_clicks(bitlink:, unit: nil, units: nil, unit_reference: nil, size: nil)
  Bitlink::LinkClick.list(
    client: self,
    bitlink: bitlink,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#bsds ⇒ Array<String>

Fetch Branded Short Domains (BSDs). [‘GET /v4/bsds`](dev.bitly.com/api-reference/#getBSDs)

Examples:

bsds = client.bsds



547
548
549
 
# File 'lib/bitly/api/client.rb', line 547

def bsds
  BSD.list(client: self)
end

#create_bitlink(long_url:, domain: nil, group_guid: nil, title: nil, tags: nil, deeplinks: nil) ⇒ Bitly::API::Bitlink

Creates a Bitlink with more options than #shorten. [‘POST /v4/bitlinks`](dev.bitly.com/api-reference/#createFullBitlink)

Examples:

bitlink = client.create_bitlink(long_url: "http://example.com", title: "An example")



93
94
95
 
# File 'lib/bitly/api/client.rb', line 93

def create_bitlink(long_url:, domain: nil, group_guid: nil, title: nil, tags: nil, deeplinks: nil)
  Bitlink.create(client: self, long_url: long_url, domain: domain, group_guid: group_guid, title: title, tags: tags, deeplinks: deeplinks)
end

#expand(bitlink:) ⇒ Bitly::API::Bitlink

Return public information about a bitlink. [‘POST /v4/expand`](dev.bitly.com/api-reference/#expandBitlink)

Examples:

bitlink = client.expand(bitlink: "bit.ly/example")



121
122
123
 
# File 'lib/bitly/api/client.rb', line 121

def expand(bitlink:)
  Bitlink.expand(client: self, bitlink: bitlink)
end

#group(group_guid:) ⇒ Bitly::API::Group

Fetch a particular group. [‘GET /v4/groups/group_guid`](dev.bitly.com/api-reference/#getGroup)

Examples:

group = client.group(guid)



348
349
350
 
# File 'lib/bitly/api/client.rb', line 348

def group(group_guid:)
  Group.fetch(client: self, group_guid: group_guid)
end

#group_bitlinks(group_guid:, size: nil, page: nil, keyword: nil, query: nil, created_before: nil, created_after: nil, modified_after: nil, archived: nil, deeplinks: nil, domain_deeplinks: nil, campaign_guid: nil, channel_guid: nil, custom_bitlink: nil, tags: nil, encoding_login: nil) ⇒ Bitly::API::Bitlink::PaginatedList

Retrieve a list of bitlinks by group [‘GET /v4/groups/group_guid/bitlinks`](dev.bitly.com/api-reference/#getBitlinksByGroup)

Examples:

bitlinks = client.group_bitlinks(group_guid: guid)



448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
 
# File 'lib/bitly/api/client.rb', line 448

def group_bitlinks(
  group_guid:,
  size: nil,
  page: nil,
  keyword: nil,
  query: nil,
  created_before: nil,
  created_after: nil,
  modified_after: nil,
  archived: nil,
  deeplinks: nil,
  domain_deeplinks: nil,
  campaign_guid: nil,
  channel_guid: nil,
  custom_bitlink: nil,
  tags: nil,
  encoding_login: nil
)
  Bitlink.list(
    client: self,
    group_guid: group_guid,
    size: size,
    page: page,
    keyword: keyword,
    query: query,
    created_before: created_before,
    created_after: created_after,
    modified_after: modified_after,
    archived: archived,
    deeplinks: deeplinks,
    domain_deeplinks: domain_deeplinks,
    campaign_guid: campaign_guid,
    channel_guid: channel_guid,
    custom_bitlink: custom_bitlink,
    tags: tags,
    encoding_login: 
  )
end

#group_countries(group_guid:, unit: nil, units: nil, size: nil, unit_reference: nil) ⇒ Bitly::API::ClickMetric::List

Gets the country click metrics for the group. [‘GET /v4/groups/group_guid/countries`](dev.bitly.com/api-reference/#getGroupMetricsByCountries)



528
529
530
531
532
533
534
535
536
537
 
# File 'lib/bitly/api/client.rb', line 528

def group_countries(group_guid:, unit: nil, units: nil, size: nil, unit_reference: nil)
  ClickMetric.list_countries_by_group(
    client: self,
    group_guid: group_guid,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#group_preferences(group_guid:) ⇒ Bitly::API::Group::Preferences

Fetch a group’s preferences. [‘GET /v4/groups/group_guid/preferences`](dev.bitly.com/api-reference/#getGroupPreferences)



374
375
376
 
# File 'lib/bitly/api/client.rb', line 374

def group_preferences(group_guid:)
  Group::Preferences.fetch(client: self, group_guid: group_guid)
end

#group_referring_networks(group_guid:, unit: nil, units: nil, size: nil, unit_reference: nil) ⇒ Bitly::API::ClickMetric::List

Gets the referring networks for the group. [‘GET /v4/groups/group_guid/referring_networks`](dev.bitly.com/api-reference/#GetGroupMetricsByReferringNetworks)



502
503
504
505
506
507
508
509
510
511
 
# File 'lib/bitly/api/client.rb', line 502

def group_referring_networks(group_guid:, unit: nil, units: nil, size: nil, unit_reference: nil)
  ClickMetric.list_referring_networks(
    client: self,
    group_guid: group_guid,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#group_shorten_counts(group_guid:) ⇒ Bitly::API::ShortenCounts

Fetch the shorten counts for a group. [‘GET /v4/groups/group_guid/shorten_counts`](dev.bitly.com/api-reference/#getGroupShortenCounts)

Examples:

shorten_counts = client.group_shorten_counts(guid: group_guid)



363
364
365
 
# File 'lib/bitly/api/client.rb', line 363

def group_shorten_counts(group_guid:)
  Bitly::API::ShortenCounts.by_group(client: self, group_guid: group_guid)
end

#groups(organization_guid: nil) ⇒ Bitly::API::Group::List

Lists groups the authorized user can see. [‘GET /v4/groups`](dev.bitly.com/api-reference/#getGroups)

Examples:

groups = client.groups



334
335
336
 
# File 'lib/bitly/api/client.rb', line 334

def groups(organization_guid: nil)
  Group.list(client: self, organization_guid: organization_guid)
end

#organization(organization_guid:) ⇒ Bitly::API::Organization

Retrieve an organization from the API. [‘GET /v4/organizations/organization_guid`](dev.bitly.com/api-reference/#getOrganization)

Examples:

organization = client.organization(organization_guid: guid)



276
277
278
 
# File 'lib/bitly/api/client.rb', line 276

def organization(organization_guid:)
  Organization.fetch(client: self, organization_guid: organization_guid)
end

#organization_shorten_counts(organization_guid:) ⇒ Bitly::API::ShortenCounts

Shorten counts by organization [‘GET /v4/organizations/organization_guid/shorten_counts`](dev.bitly.com/api-reference/#getOrganizationShortenCounts)

Examples:

shorten_counts = client.organization_shorten_counts(organization_guid: organization_guid)



291
292
293
 
# File 'lib/bitly/api/client.rb', line 291

def organization_shorten_counts(organization_guid:)
  Bitly::API::ShortenCounts.by_organization(client: self, organization_guid: organization_guid)
end

#organizations ⇒ Bitly::API::Organization::List

Get a list of organizations from the API. [‘GET /v4/organizations`](dev.bitly.com/api-reference/#getOrganizations)

Examples:

organizations = client.organizations



262
263
264
 
# File 'lib/bitly/api/client.rb', line 262

def organizations
  Organization.list(client: self)
end

#qrcode(qrcode_id:) ⇒ Bitly::API::Qrcode

Fetch a qr code by ID [‘GET /v4/qr-codes/qrcode_id`](dev.bitly.com/api-reference/#getQRCodeByIdPublic)

Examples:

qrcode = client.qrcode(qrcode_id: "a1b2c3")



559
560
561
 
# File 'lib/bitly/api/client.rb', line 559

def qrcode(qrcode_id:)
  Qrcode.fetch(client: self, qrcode_id: qrcode_id)
end

#request(path:, method: 'GET', params: {}, headers: {}) ⇒ Bitly::HTTP::Response

Makes a request to the API by building up a Bitly::HTTP::Request and using the HTTP client to make that request and return a Bitly::HTTP::Response.

Examples:

client.request("/shorten", method: "POST", params: { long_url => "https://example.com" })



50
51
52
53
54
55
56
57
 
# File 'lib/bitly/api/client.rb', line 50

def request(path:, method: 'GET', params: {}, headers: {})
  params = params.select { |k,v| !v.nil? }
  headers = default_headers.merge(headers)
  uri = Bitly::API::BASE_URL.dup
  uri.path += path
  request = Bitly::HTTP::Request.new(uri: uri, method: method, params: params, headers: headers)
  @http.request(request)
end

#shorten(long_url:, domain: nil, group_guid: nil) ⇒ Bitly::API::Bitlink

Shortens a long URL. [‘POST /v4/shorten`](dev.bitly.com/api-reference/#createBitlink)

Examples:

client.shorten(long_url: "http://example.com")



72
73
74
 
# File 'lib/bitly/api/client.rb', line 72

def shorten(long_url:, domain: nil, group_guid: nil)
  Bitlink.shorten(client: self, long_url: long_url, domain: domain, group_guid: group_guid)
end

#sorted_bitlinks(group_guid:, sort: "clicks", unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Object

Returns a list of Bitlinks sorted by clicks. [‘GET /v4/groups/group_guid/bitlinks/sort`](dev.bitly.com/api-reference/#getSortedBitlinks)

The API returns a separate list of the links and the click counts, but this method assigns the number of clicks for each link to the Bitlink object and sorts the resulting list in descending order.

Sorted lists are not paginated, so do not have any pagination detail.

Examples:

links = client.sorted_list(group_guid: guid)



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/bitly/api/client.rb', line 151

def sorted_bitlinks(
  group_guid:,
  sort: "clicks",
  unit: nil,
  units: nil,
  unit_reference: nil,
  size: nil
)
  Bitlink.sorted_list(
    client: self,
    group_guid: group_guid,
    sort: sort,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#update_bitlink(bitlink:, archived: nil, tags: nil, created_at: nil, title: nil, deeplinks: nil, created_by: nil, long_url: nil, client_id: nil, custom_bitlinks: nil, link: nil, id: nil, references: nil) ⇒ Object

Update a Bitlink. [‘PATCH /v4/bitlink/#bitlink`](dev.bitly.com/api-reference/#updateBitlink)

The parameters listed below are from the documentation. Some only work if you have a Bitly Pro account.

Examples:

client.update_bitlink(bitlink: bitlink, title: "New title")



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/bitly/api/client.rb', line 194

def update_bitlink(
  bitlink:,
  archived: nil,
  tags: nil,
  created_at: nil,
  title: nil,
  deeplinks: nil,
  created_by: nil,
  long_url: nil,
  client_id: nil,
  custom_bitlinks: nil,
  link: nil,
  id: nil,
  references: nil
)
  bitlink = Bitlink.new(data: { "id" => bitlink }, client: self)
  bitlink.update(
    archived: archived,
    tags: tags,
    created_at: created_at,
    title: title,
    deeplinks: deeplinks,
    created_by: created_by,
    long_url: long_url,
    client_id: client_id,
    custom_bitlinks: custom_bitlinks,
    link: link,
    id: id,
    references: references
  )
end

#update_group(group_guid:, name: nil, organization_guid: nil, bsds: nil) ⇒ Bitly::API::Group

Allows you to update a group’s name, organization or BSDs. [‘PATCH /v4/groups/group_guid`](dev.bitly.com/api-reference/#updateGroup)

Examples:

client.update_group(group_guid: group_guid, name: "New Name", organization_guid: "aaabbb")



405
406
407
408
409
410
411
412
 
# File 'lib/bitly/api/client.rb', line 405

def update_group(group_guid:, name: nil, organization_guid: nil, bsds: nil)
  group = Group.new(data: { "guid" => group_guid }, client: self)
  group.update(
    name: name,
    organization_guid: organization_guid,
    bsds: bsds
  )
end

#update_group_preferences(group_guid:, domain_preference:) ⇒ Bitly::API::Group::Preferences

Update a group’s preferences. [‘PATCH /v4/groups/group_guid/preferences`](dev.bitly.com/api-reference/#updateGroupPreferences)



387
388
389
390
 
# File 'lib/bitly/api/client.rb', line 387

def update_group_preferences(group_guid:, domain_preference:)
  group_preferences = Group::Preferences.new(data: { "group_guid" => group_guid }, client: self)
  group_preferences.update(domain_preference: domain_preference)
end

#update_user(name: nil, default_group_guid: nil) ⇒ Bitly::API::User

Allows you to update the authorized user’s name or default group guid.

‘PATCH /v4/user`](dev.bitly.com/api-reference/#updateUser)

Examples:

client.update_user(name: "New Name", default_group_guid: "aaabbb")



318
319
320
321
 
# File 'lib/bitly/api/client.rb', line 318

def update_user(name: nil, default_group_guid: nil)
  user = Bitly::API::User.new(client: self, data: {})
  user.update(name: name, default_group_guid: default_group_guid)
end

#user ⇒ Bitly::API::User

Gets the authorized user from the API. [‘GET /v4/user`](dev.bitly.com/api-reference/#getUser)

Examples:

user = client.user



303
304
305
 
# File 'lib/bitly/api/client.rb', line 303

def user
  User.fetch(client: self)
end