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)

Parameters:

  • http (Bitly::HTTP::Client) (defaults to: Bitly::HTTP::Client.new) —

    An HTTP client, you can pass your own if you have a custom client you would like to use. Custom clients must have a request method that takes a Bitly::HTTP::Request object as a single parameter and returns a Bitly::HTTP::Response object (or an object that behaves like one).

  • token (String) —

    An OAuth token for a user authorized with the API.



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")

Parameters:

  • bitlink (String) —

    The bitlink you want information about

Returns:



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)

Parameters:

  • bitlink (String) —

    The Bitlink for which you want the clicks

  • sort (String) —

    The data to sort on. Default and only option is “clicks”.

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



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

Returns:

  • (Array<String>) 


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")

Parameters:

  • long_url (String) —

    A long URL that you want shortened

  • domain (String) (defaults to: nil) —

    The bitly domain you want to shorten, API default is “bit.ly”

  • group_guid (String) (defaults to: nil) —

    The GUID of the group for which you want to shorten this URL

  • title (String) (defaults to: nil) —

    A descriptive title for the link

  • tags (Array<String>) (defaults to: nil) —

    Some tags for the Bitlink

  • deeplinks (Array<Bitly::API::Bitlink::Deeplink>) (defaults to: nil)

Returns:



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")

Parameters:

  • bitlink (String) —

    The bitlink you want information about

Returns:



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)

Parameters:

  • guid (String) —

    The guid of the group you want.

Returns:



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)

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • group_guid (String) —

    The group guid for which you want bitlinks

  • size (Integer) (defaults to: nil) —

    The number of Bitlinks to return, max 100

  • page (Integer) (defaults to: nil) —

    The page of bitlinks to request

  • keyword (String) (defaults to: nil) —

    Custom keyword to filter on history entries

  • query (String) (defaults to: nil) —

    A value to search for Bitlinks

  • created_before (Integer) (defaults to: nil) —

    Timestamp as an integer unix epoch

  • created_after (Integer) (defaults to: nil) —

    Timestamp as an integer unix epoch

  • modified_after (Integer) (defaults to: nil) —

    Timestamp as an integer unix epoch

  • archived (String) (defaults to: nil) —

    Whether or not to include archived Bitlinks. One of “on”, “off” or “both”. Defaults to “off”.

  • deeplinks (String) (defaults to: nil) —

    Filter to only Bitlinks that contain deeplinks. One of “on”, “off” or “both”. Defaults to “both”.

  • domain_deeplinks (String) (defaults to: nil) —

    Filter to only Bitlinks that contain deeplinks configured with a custom domain. One of “on”, “off” or “both”. Defaults to “both”.

  • campaign_guid (String) (defaults to: nil) —

    Filter to return only links for the given campaign GUID, can be provided

  • channel_guid (String) (defaults to: nil) —

    Filter to return only links for the given channel GUID, can be provided, overrides all other parameters

  • custom_bitlink (String) (defaults to: nil) —

    Filter to return only custom Bitlinks. One of “on”, “off” or “both”. Defaults to “both”.

  • tags (Array<String>) (defaults to: nil) —

    Filter by the given tags.

  • encoding_login (Array<String>) (defaults to: nil) —

    Filter by the login of the authenticated user that created the Bitlink.

Returns:



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)

Parameters:

  • group_guid (String) —

    The guid of the group

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



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)

Parameters:

  • group_guid (String) —

    The group’s guid

Returns:



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)

Parameters:

  • group_guid (String) —

    The guid of the group

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



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)

Parameters:

  • guid (String) —

    The guid of the group for which you want the shorten counts.

Returns:



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

Parameters:

  • organization (String) —

    The organization guid of the organization for which you want the available groups.

Returns:



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)

Parameters:

  • organization_guid (String) —

    An organization guid

Returns:



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)

Parameters:

  • organization_guid (String) —

    The guid of the organization for which you want shorten counts

Returns:



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

Returns:



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

def organizations
  Organization.list(client: self)
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" })

Parameters:

  • path (String) —

    The resource path

  • method (String) (defaults to: 'GET') —

    The HTTP method to use to request the path

  • params (Hash<String, String>) (defaults to: {}) —

    The parameters to pass to the API

  • headers (Hash<String, String>) (defaults to: {}) —

    Custom headers for the request

Returns:



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")

Parameters:

  • long_url (String) —

    The URL you want to shorten

  • domain (String) (defaults to: nil) —

    The domain you want to shorten the URL with. “bit.ly” by default.

  • group_guid (String) (defaults to: nil) —

    The group you want shorten this URL under

Returns:



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)

Parameters:

  • group_guid (String) —

    The group for which you want to return links

  • sort (String) (defaults to: "clicks") —

    The data to sort on. Default and only option is “clicks”.

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50



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")

Parameters:

  • archived (Boolean) (defaults to: nil)
  • tags (Array<String>) (defaults to: nil)
  • created_at (String) (defaults to: nil)
  • title (String) (defaults to: nil)
  • deeplinks (Array<Bitly::API::Bitlink::Deeplink>) (defaults to: nil)
  • created_by (String) (defaults to: nil)
  • long_url (String) (defaults to: nil)
  • client_id (String) (defaults to: nil)
  • custom_bitlinks (Array<String>) (defaults to: nil)
  • link (String) (defaults to: nil)
  • id (String) (defaults to: nil)
  • references (Hash<String, String>) (defaults to: nil) 


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")

Parameters:

  • group_guid (String) —

    The group’s guid

  • name (String) (defaults to: nil) —

    A new name

  • organization_guid (String) (defaults to: nil) —

    A new organization guid

  • bsds (Array<String>) (defaults to: nil) —

    An array of branded short domains

Returns:



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)

Parameters:

  • group_guid (String) —

    The group’s guid

  • domain_preference (String) —

    The new domain preference for this group

Returns:



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")

Parameters:

  • name (String) (defaults to: nil) —

    A new name

  • default_group_guid (String) (defaults to: nil) —

    A new default guid

Returns:



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

Returns:



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

def user
  User.fetch(client: self)
end