class Bitly::API::Client

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.

Constants

USER_AGENT

Public Class Methods

new(http: Bitly::HTTP::Client.new, token:) click to toggle source

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

@example

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

@param http [Bitly::HTTP::Client] 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).

@param token [String] An OAuth token for a user authorized with the API.

@return [Bitly::API::Client]

# File lib/bitly/api/client.rb, line 31
def initialize(http: Bitly::HTTP::Client.new, token:)
  @http = http
  @token = token
end

Public Instance Methods

bsds() click to toggle source

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

@example

bsds = client.bsds

@return [Array<String>]

# File lib/bitly/api/client.rb, line 560
def bsds
  BSD.list(client: self)
end
delete_group(group_guid:) click to toggle source

Deletes a group. [`DELETE /v4/groups/{group_guid}`](dev.bitly.com/v4/#operation/deleteGroup)

@example

client.delete_group(group_guid: group_guid)

@return [Nil]

# File lib/bitly/api/client.rb, line 495
def delete_group(group_guid:)
  group = Group.new(data: { "guid" => group_guid }, client: self)
  group.delete
end
expand(bitlink:) click to toggle source

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

@example

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

@param bitlink [String] The bitlink you want information about

@return [Bitly::API::Bitlink]

# File lib/bitly/api/client.rb, line 121
def expand(bitlink:)
  Bitlink.expand(client: self, bitlink: bitlink)
end
group(group_guid:) click to toggle source

Fetch a particular group. [`GET /v4/groups/{group_guid}`](dev.bitly.com/v4/#operation/getGroup)

@example

group = client.group(guid)

@param guid [String] The guid of the group you want.

@return [Bitly::API::Group]

# File lib/bitly/api/client.rb, line 348
def group(group_guid:)
  Group.fetch(client: self, group_guid: group_guid)
end
group_countries(group_guid:, unit: nil, units: nil, size: nil, unit_reference: nil) click to toggle source

Gets the country click metrics for the group. [`GET /v4/groups/{group_guid}/countries`](dev.bitly.com/v4/#operation/getGroupMetricsByCountries)

@param group_guid [String] The guid of the group @param unit [String] A unit of time. Default is “day” and can be

"minute", "hour", "day", "week" or "month"

@param units [Integer] An integer representing the time units to query

data for. pass -1 to return all units of time. Defaults to -1.

@param unit_reference [String] An ISO-8601 timestamp, indicating the

most recent time for which to pull metrics. Will default to current
time.

@param size [Integer] The number of links to be returned. Defaults to 50

@return [Bitly::API::ClickMetric::List]

# File lib/bitly/api/client.rb, line 541
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:) click to toggle source

Fetch a group's preferences. [`GET /v4/groups/{group_guid}/preferences`](dev.bitly.com/v4/#operation/getGroupPreferences)

@param group_guid [String] The group's guid

@return [Bitly::API::Group::Preferences]

# 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) click to toggle source

Gets the referring networks for the group. [`GET /v4/groups/{group_guid}/referring_networks`](dev.bitly.com/v4/#operation/GetGroupMetricsByReferringNetworks)

@param group_guid [String] The guid of the group @param unit [String] A unit of time. Default is “day” and can be

"minute", "hour", "day", "week" or "month"

@param units [Integer] An integer representing the time units to query

data for. pass -1 to return all units of time. Defaults to -1.

@param unit_reference [String] An ISO-8601 timestamp, indicating the

most recent time for which to pull metrics. Will default to current
time.

@param size [Integer] The number of links to be returned. Defaults to 50

@return [Bitly::API::ClickMetric::List]

# File lib/bitly/api/client.rb, line 515
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:) click to toggle source

Fetch the shorten counts for a group. [`GET /v4/groups/{group_guid}/shorten_counts`](dev.bitly.com/v4/#operation/getGroupShortenCounts)

@example

shorten_counts = client.group_shorten_counts(guid: group_guid)

@param guid [String] The guid of the group for which you want the

shorten counts.

@return [Bitly::API::ShortenCounts]

# 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) click to toggle source

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

@example

groups = client.groups

@param organization [String] The organization guid of the organization

for which you want the available groups.

@return [Bitly::API::Group::List]

# File lib/bitly/api/client.rb, line 334
def groups(organization_guid: nil)
  Group.list(client: self, organization_guid: organization_guid)
end
oauth_app(client_id:) click to toggle source

Fetch OAuth application by client ID [`GET /v4/apps/{client_id}`)](dev.bitly.com/v4/#operation/getOAuthApp)

@example

app = client.oauth_app(client_id: "client_id")

@return Bitly::API::OAuthApp

# File lib/bitly/api/client.rb, line 572
def oauth_app(client_id:)
  OAuthApp.fetch(client: self, client_id: client_id)
end
organization(organization_guid:) click to toggle source

Retrieve an organization from the API. [`GET /v4/organizations/{organization_guid}`](dev.bitly.com/v4/#operation/getOrganization)

@example

organization = client.organization(organization_guid: guid)

@param organization_guid [String] An organization guid

@return [Bitly::API::Organization]

# 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:) click to toggle source

Shorten counts by organization [`GET /v4/organizations/{organization_guid}/shorten_counts`](dev.bitly.com/v4/#operation/getOrganizationShortenCounts)

@example

shorten_counts = client.organization_shorten_counts(organization_guid: organization_guid)

@param organization_guid [String] The guid of the organization for which

you want shorten counts

@return [Bitly::API::ShortenCounts]

# 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() click to toggle source

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

@example

organizations = client.organizations

@return [Bitly::API::Organization::List]

# File lib/bitly/api/client.rb, line 262
def organizations
  Organization.list(client: self)
end
request(path:, method: 'GET', params: {}, headers: {}) click to toggle source

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.

@example

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

@param path [String] The resource path @param method [String] The HTTP method to use to request the path @param params [Hash<String, String>] The parameters to pass to the API @param headers [Hash<String, String>] Custom headers for the request

@return [Bitly::HTTP::Response]

# 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) click to toggle source

Shortens a long URL. [`POST /v4/shorten`](dev.bitly.com/v4/#operation/createBitlink)

@example

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

@param long_url [String] The URL you want to shorten @param domain [String] The domain you want to shorten the URL with.

"bit.ly" by default.

@param group_guid [String] The group you want shorten this URL under

@return [Bitly::API::Bitlink]

# 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
update_group(group_guid:, name: nil, organization_guid: nil, bsds: nil) click to toggle source

Allows you to update a group's name, organization or BSDs. [`PATCH /v4/groups/{group_guid}`](dev.bitly.com/v4/#operation/updateGroup)

@example

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

@param group_guid [String] The group's guid @param name [String] A new name @param organization_guid [String] A new organization guid @param bsds [Array<String>] An array of branded short domains

@return [Bitly::API::Group]

# 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:) click to toggle source

Update a group's preferences. [`PATCH /v4/groups/{group_guid}/preferences`](dev.bitly.com/v4/#operation/updateGroupPreferences)

@param group_guid [String] The group's guid @param domain_preference [String] The new domain preference for this

group

@return [Bitly::API::Group::Preferences]

# 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) click to toggle source

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

`PATCH /v4/user`](dev.bitly.com/v4/#operation/updateUser)

@example

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

@param name [String] A new name @param default_group_guid [String] A new default guid

@return [Bitly::API::User]

# 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() click to toggle source

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

@example

user = client.user

@return [Bitly::API::User]

# File lib/bitly/api/client.rb, line 303
def user
  User.fetch(client: self)
end

Private Instance Methods

default_headers() click to toggle source
# File lib/bitly/api/client.rb, line 578
def default_headers
  {
    "User-Agent" => USER_AGENT,
    "Authorization" => "Bearer #{@token}",
    "Accept" => "application/json",
    "Content-Type" => "application/json"
  }
end