Class: Bitly::API::Group

Inherits:
Object
  • Object
show all
Includes:
Base
Defined in:
lib/bitly/api/group.rb,
lib/bitly/api/group/preferences.rb

Overview

A Group represents a subdivision of an Organization. Most API actions are taken on behalf of a user and group and groups become a container for Bitlinks and metrics.

Defined Under Namespace

Classes: List, Preferences

Instance Attribute Summary

Attributes included from Base

#response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Base

#assign_attributes

Constructor Details

#initialize(data:, client:, response: nil, organization: nil) ⇒ Bitly::API::Group

Creates a new ‘Bitly::API::Group` object.

Examples:

group = Bitly::API::Group.new(data: group_data, client: client)

Parameters:



87
88
89
90
91
92
 
# File 'lib/bitly/api/group.rb', line 87

def initialize(data:, client:, response: nil, organization: nil)
  assign_attributes(data)
  @client = client
  @response = response
  @organization = organization
end

Class Method Details

.attributes ⇒ Array<Symbol>

Returns The attributes the API returns for a group.

Returns:

  • (Array<Symbol>) —

    The attributes the API returns for a group



62
63
64
 
# File 'lib/bitly/api/group.rb', line 62

def self.attributes
  [:name, :guid, :is_active, :role, :bsds, :organization_guid]
end

.fetch(client:, group_guid:) ⇒ Bitly::API::Group

Retrieve a group from the API. It receives an authorized ‘Bitly::API::Client` object and a group guid and uses it to request

the `/groups/:group_guid` endpoint.

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

Examples:

group = Bitly::API::Group.fetch(client: client, guid: guid)

Parameters:

Returns:



56
57
58
59
 
# File 'lib/bitly/api/group.rb', line 56

def self.fetch(client:, group_guid:)
  response = client.request(path: "/groups/#{group_guid}")
  Group.new(data: response.body, client: client, response: response)
end

.list(client:, organization_guid: nil) ⇒ Bitly::API::Group::List

Get a list of groups from the API. It receives an authorized ‘Bitly::API::Client` object and uses it to request the `/groups` endpoint, optionally passing an organization guid. [`GET /v4/groups`](dev.bitly.com/api-reference/#getGroups)

Examples:

groups = Bitly::API::Group.list(client: client)

Parameters:

Returns:



34
35
36
37
38
39
40
41
 
# File 'lib/bitly/api/group.rb', line 34

def self.list(client:, organization_guid: nil)
  params = { "organization_guid" => organization_guid }
  response = client.request(path: "/groups", params: params)
  groups = response.body["groups"].map do |group|
    Group.new(data: group, client: client)
  end
  List.new(items: groups, response: response)
end

.time_attributes ⇒ Array<Symbol>

converted to ‘Time` objects.

Returns:

  • (Array<Symbol>) —

    The attributes the API returns that need to be



67
68
69
 
# File 'lib/bitly/api/group.rb', line 67

def self.time_attributes
  [:created, :modified]
end

Instance Method Details

Gets the Bitlinks for the group. [‘GET /v4/groups/group_guid/bitlinks`](dev.bitly.com/api-reference/#getBitlinksByGroup)

Returns:



164
165
166
 
# File 'lib/bitly/api/group.rb', line 164

def bitlinks
  Bitly::API::Bitlink.list(client: @client, group_guid: guid)
end

#countries(unit: nil, units: nil, unit_reference: nil, size: 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:

  • 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:



207
208
209
210
211
212
213
214
215
216
 
# File 'lib/bitly/api/group.rb', line 207

def countries(unit: nil, units: nil, unit_reference: nil, size: nil)
  ClickMetric.list_countries_by_group(
    client: @client,
    group_guid: guid,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#organization ⇒ Bitly::API::Organization

Fetch the organization for the group. [‘GET /v4/organizations/organization_guid`)](dev.bitly.com/api-reference/#getOrganization)

Returns:



99
100
101
 
# File 'lib/bitly/api/group.rb', line 99

def organization
  @organization ||= Organization.fetch(client: @client, organization_guid: organization_guid)
end

#preferences ⇒ Bitly::API::Group::Preferences

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

Returns:



108
109
110
 
# File 'lib/bitly/api/group.rb', line 108

def preferences
  @preferences ||= Group::Preferences.fetch(client: @client, group_guid: guid)
end

#referring_networks(unit: nil, units: nil, unit_reference: nil, size: 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:

  • 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:



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/bitly/api/group.rb', line 182

def referring_networks(unit: nil, units: nil, unit_reference: nil, size: nil)
  ClickMetric.list_referring_networks(
    client: @client,
    group_guid: guid,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#shorten_counts ⇒ Bitly::API::ShortenCounts

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

Returns:



155
156
157
 
# File 'lib/bitly/api/group.rb', line 155

def shorten_counts
  ShortenCounts.by_group(client: @client, group_guid: guid)
end

#tags ⇒ Array<String>

Fetch the group’s tags [‘GET /v4/groups/group_guid/tags`](dev.bitly.com/api-reference/#getGroupTags)

Returns:

  • (Array<String>) 


117
118
119
 
# File 'lib/bitly/api/group.rb', line 117

def tags
  @tags ||= @client.request(path: "/groups/#{guid}/tags").body["tags"]
end

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

Allows you to update the group’s name, organization or BSDs. If you update the organization guid and have already loaded the organization, it is nilled out so it can be reloaded with the correct guid [‘PATCH /v4/groups/group_guid`](dev.bitly.com/api-reference/#updateGroup)

Examples:

group.update(name: "New Name", organization_guid: "aaabbb")

Parameters:

  • 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:



136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/bitly/api/group.rb', line 136

def update(name: nil, organization_guid: nil, bsds: nil)
  params = {
    "name" => name,
    "bsds" => bsds
  }
  if organization_guid
    params["organization_guid"] = organization_guid
    @organization = nil
  end
  @response = @client.request(path: "/groups/#{guid}", method: "PATCH", params: params)
  assign_attributes(@response.body)
  self
end