Module: Discordrb::API

Defined in:
lib/discordrb/api.rb

Overview

List of methods representing endpoints in Discord's API

Defined Under Namespace

Modules: Application, Channel, Interaction, Invite, Server, User, Webhook

Constant Summary collapse

APIBASE =

The base URL of the Discord REST API.

'https://discord.com/api/v9'
CDN_URL =

The URL of Discord's CDN

'https://cdn.discordapp.com'

Class Method Summary collapse

Class Method Details

.achievement_icon_url(application_id, achievement_id, icon_hash, format = 'webp') ⇒ Object

Make an achievement icon URL from application ID, achievement ID, and icon hash



244
245
246
 
# File 'lib/discordrb/api.rb', line 244

def achievement_icon_url(application_id, achievement_id, icon_hash, format = 'webp')
  "#{cdn_url}/app-assets/#{application_id}/achievements/#{achievement_id}/icons/#{icon_hash}.#{format}"
end

.api_base ⇒ String

Returns the currently used API base URL.

Returns:

  • (String) —

    the currently used API base URL.



20
21
22
 
# File 'lib/discordrb/api.rb', line 20

def api_base
  @api_base || APIBASE
end

.api_base=(value) ⇒ Object

Sets the API base URL to something.



25
26
27
 
# File 'lib/discordrb/api.rb', line 25

def api_base=(value)
  @api_base = value
end

.app_cover_url(app_id, cover_id, format = 'webp') ⇒ Object

make a cover image URL from application and cover IDs.



282
283
284
 
# File 'lib/discordrb/api.rb', line 282

def app_cover_url(app_id, cover_id, format = 'webp')
  "#{cdn_url}/app-icons/#{app_id}/#{cover_id}.#{format}"
end

.app_icon_url(app_id, icon_id, format = 'webp') ⇒ Object

Make an icon URL from application and icon IDs



209
210
211
 
# File 'lib/discordrb/api.rb', line 209

def app_icon_url(app_id, icon_id, format = 'webp')
  "#{cdn_url}/app-icons/#{app_id}/#{icon_id}.#{format}"
end

.asset_url(application_id, asset_id, format = 'webp') ⇒ Object

Make an asset URL from application and asset IDs



239
240
241
 
# File 'lib/discordrb/api.rb', line 239

def asset_url(application_id, asset_id, format = 'webp')
  "#{cdn_url}/app-assets/#{application_id}/#{asset_id}.#{format}"
end

.avatar_decoration_url(avatar_decoration_id, format = 'png') ⇒ Object

make an avatar decoration URL from an avatar decoration ID.



257
258
259
 
# File 'lib/discordrb/api.rb', line 257

def avatar_decoration_url(avatar_decoration_id, format = 'png')
  "#{cdn_url}/avatar-decoration-presets/#{avatar_decoration_id}.#{format}"
end

Make a banner URL from server and banner IDs



229
230
231
 
# File 'lib/discordrb/api.rb', line 229

def banner_url(server_id, banner_id, format = 'webp')
  "#{cdn_url}/banners/#{server_id}/#{banner_id}.#{format}"
end

.bot_name ⇒ String

Returns the bot name, previously specified using bot_name=.

Returns:



35
36
37
 
# File 'lib/discordrb/api.rb', line 35

def bot_name
  @bot_name
end

.bot_name=(value) ⇒ Object

Sets the bot name to something. Used in user_agent. For the bot's username, see Profile#username=.



40
41
42
 
# File 'lib/discordrb/api.rb', line 40

def bot_name=(value)
  @bot_name = value
end

.cdn_url ⇒ String

Returns the currently used CDN url.

Returns:

  • (String) —

    the currently used CDN url



30
31
32
 
# File 'lib/discordrb/api.rb', line 30

def cdn_url
  @cdn_url || CDN_URL
end

.discovery_splash_url(server_id, splash_id, format = 'webp') ⇒ Object

Make a discovery splash URL from server and splash IDs



224
225
226
 
# File 'lib/discordrb/api.rb', line 224

def discovery_splash_url(server_id, splash_id, format = 'webp')
  "#{cdn_url}/discovery-splashes/#{server_id}/#{splash_id}.#{format}"
end

.emoji_icon_url(emoji_id, format = 'webp') ⇒ Object

Make an emoji icon URL from emoji ID



234
235
236
 
# File 'lib/discordrb/api.rb', line 234

def emoji_icon_url(emoji_id, format = 'webp')
  "#{cdn_url}/emojis/#{emoji_id}.#{format}"
end

.gateway(token) ⇒ Object

Get the gateway to be used



317
318
319
320
321
322
323
324
325
 
# File 'lib/discordrb/api.rb', line 317

def gateway(token)
  request(
    :gateway,
    nil,
    :get,
    "#{api_base}/gateway",
    Authorization: token
  )
end

.gateway_bot(token) ⇒ Object

Get the gateway to be used, with additional information for sharding and session start limits



329
330
331
332
333
334
335
336
337
 
# File 'lib/discordrb/api.rb', line 329

def gateway_bot(token)
  request(
    :gateway_bot,
    nil,
    :get,
    "#{api_base}/gateway/bot",
    Authorization: token
  )
end

.handle_preemptive_rl(headers, mutex, key) ⇒ Object

Handles pre-emptive rate limiting by waiting the given mutex by the difference of the Date header to the X-Ratelimit-Reset header, thus making sure we don't get 429'd in any subsequent requests.



180
181
182
183
184
185
 
# File 'lib/discordrb/api.rb', line 180

def handle_preemptive_rl(headers, mutex, key)
  Discordrb::LOGGER.ratelimit "RL bucket depletion detected! Date: #{headers[:date]} Reset: #{headers[:x_ratelimit_reset]}"
  delta = headers[:x_ratelimit_reset_after].to_f
  Discordrb::LOGGER.warn("Locking RL mutex (key: #{key}) for #{delta} seconds pre-emptively")
  sync_wait(delta, mutex)
end

.icon_url(server_id, icon_id, format = 'webp') ⇒ Object

Make an icon URL from server and icon IDs



204
205
206
 
# File 'lib/discordrb/api.rb', line 204

def icon_url(server_id, icon_id, format = 'webp')
  "#{cdn_url}/icons/#{server_id}/#{icon_id}.#{format}"
end

.mutex_wait(mutex) ⇒ Object

Wait for a specified mutex to unlock and do nothing with it afterwards.



72
73
74
75
 
# File 'lib/discordrb/api.rb', line 72

def mutex_wait(mutex)
  mutex.lock
  mutex.unlock
end

.nameplate_url(nameplate_asset, format = 'webm') ⇒ Object

make a nameplate URL from the nameplate asset.



267
268
269
 
# File 'lib/discordrb/api.rb', line 267

def nameplate_url(nameplate_asset, format = 'webm')
  "#{cdn_url}/assets/collectibles/#{nameplate_asset.delete_suffix('/')}/asset.#{format}"
end

.oauth_application(token) ⇒ Object

Get the bot's OAuth application's information



306
307
308
309
310
311
312
313
314
 
# File 'lib/discordrb/api.rb', line 306

def oauth_application(token)
  request(
    :oauth2_applications_me,
    nil,
    :get,
    "#{api_base}/applications/@me",
    Authorization: token
  )
end

.raw_request(type, attributes) ⇒ Object

Performs a RestClient request.

Parameters:

  • type (Symbol) —

    The type of HTTP request to use.

  • attributes (Array) —

    The attributes for the request.



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/discordrb/api.rb', line 80

def raw_request(type, attributes)
  RestClient.send(type, *attributes)
rescue RestClient::Forbidden => e
  # HACK: for #request, dynamically inject restclient's response into NoPermission - this allows us to rate limit
  noprm = Discordrb::Errors::NoPermission.new
  noprm.define_singleton_method(:_rc_response) { e.response }
  raise noprm, "The bot doesn't have the required permission to do this!"
rescue RestClient::BadGateway
  Discordrb::LOGGER.warn('Got a 502 while sending a request! Not a big deal, retrying the request')
  retry
end

.request(key, major_parameter, type, *attributes) ⇒ Object

Make an API request, including rate limit handling.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/discordrb/api.rb', line 93

def request(key, major_parameter, type, *attributes)
  # Add a custom user agent
  attributes.last[:user_agent] = user_agent if attributes.last.is_a? Hash

  # The most recent Discord rate limit requirements require the support of major parameters, where a particular route
  # and major parameter combination (*not* the HTTP method) uniquely identifies a RL bucket.
  key = [key, major_parameter].freeze

  begin
    mutex = @mutexes[key] ||= Mutex.new

    # Lock and unlock, i.e. wait for the mutex to unlock and don't do anything with it afterwards
    mutex_wait(mutex)

    # If the global mutex happens to be locked right now, wait for that as well.
    mutex_wait(@global_mutex) if @global_mutex.locked?

    response = nil
    begin
      response = raw_request(type, attributes)
    rescue RestClient::Exception => e
      response = e.response

      if response.body && !e.is_a?(RestClient::TooManyRequests)
        data = JSON.parse(response.body)
        err_klass = Discordrb::Errors.error_class_for(data['code'] || 0)
        e = err_klass.new(data['message'], data['errors'])

        Discordrb::LOGGER.error(e.full_message)
      end

      raise e
    rescue Discordrb::Errors::NoPermission => e
      if e.respond_to?(:_rc_response)
        response = e._rc_response
      else
        Discordrb::LOGGER.warn("NoPermission doesn't respond_to? _rc_response!")
      end

      raise e
    ensure
      if response
        handle_preemptive_rl(response.headers, mutex, key) if response.headers[:x_ratelimit_remaining] == '0' && !mutex.locked?
      else
        Discordrb::LOGGER.ratelimit('Response was nil before trying to preemptively rate limit!')
      end
    end
  rescue RestClient::TooManyRequests => e
    # If the 429 is from the global RL, then we have to use the global mutex instead.
    mutex = @global_mutex if e.response.headers[:x_ratelimit_global] == 'true'

    unless mutex.locked?
      response = JSON.parse(e.response)
      wait_seconds = response['retry_after'] ? response['retry_after'].to_f : e.response.headers[:retry_after].to_i
      Discordrb::LOGGER.ratelimit("Locking RL mutex (key: #{key}) for #{wait_seconds} seconds due to Discord rate limiting")
      trace("429 #{key.join(' ')}")

      # Wait the required time synchronized by the mutex (so other incoming requests have to wait) but only do it if
      # the mutex isn't locked already so it will only ever wait once
      sync_wait(wait_seconds, mutex)
    end

    retry
  end

  # Endpoints that use Elasticsearch can return a 202 when the index isn't ready yet. Wait the
  # amount of time indicated by the response body, and then recursively retry and return the request.
  if response&.code == 202 && response&.body
    body = JSON.parse(response.body)

    if body['code'] == 110_000
      case body['retry_after']
      when 0, 1, nil
        sleep(rand(4.5..5.0))
      else
        sleep(body['retry_after'])
      end

      return request(*key, type, *attributes)
    end
  end

  response
end

.reset_mutexes ⇒ Object

Resets all rate limit mutexes



61
62
63
64
 
# File 'lib/discordrb/api.rb', line 61

def reset_mutexes
  @mutexes = {}
  @global_mutex = Mutex.new
end

.role_icon_url(role_id, icon_hash, format = 'webp') ⇒ String

Parameters:

  • role_id (String, Integer)
  • icon_hash (String)
  • format ('webp', 'png', 'jpeg') (defaults to: 'webp')

Returns:



252
253
254
 
# File 'lib/discordrb/api.rb', line 252

def role_icon_url(role_id, icon_hash, format = 'webp')
  "#{cdn_url}/role-icons/#{role_id}/#{icon_hash}.#{format}"
end

.scheduled_event_cover_url(scheduled_event_id, cover_id, format = 'webp', size = nil) ⇒ Object

make a scheduled event cover URL from a scheduled event ID and a cover ID.



277
278
279
 
# File 'lib/discordrb/api.rb', line 277

def scheduled_event_cover_url(scheduled_event_id, cover_id, format = 'webp', size = nil)
  "#{cdn_url}/guild-events/#{scheduled_event_id}/#{cover_id}.#{format}#{"?size=#{size}" if size}"
end

.server_tag_badge_url(server_id, badge_id, format = 'webp') ⇒ Object

make a server tag badge URL from a server ID and badge ID.



272
273
274
 
# File 'lib/discordrb/api.rb', line 272

def server_tag_badge_url(server_id, badge_id, format = 'webp')
  "#{cdn_url}/guild-tag-badges/#{server_id}/#{badge_id}.#{format}"
end

.splash_url(server_id, splash_id, format = 'webp') ⇒ Object

Make a splash URL from server and splash IDs



219
220
221
 
# File 'lib/discordrb/api.rb', line 219

def splash_url(server_id, splash_id, format = 'webp')
  "#{cdn_url}/splashes/#{server_id}/#{splash_id}.#{format}"
end

.static_nameplate_url(nameplate_asset, format = 'png') ⇒ Object

make a static nameplate URL from the nameplate asset.



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

def static_nameplate_url(nameplate_asset, format = 'png')
  "#{cdn_url}/assets/collectibles/#{nameplate_asset.delete_suffix('/')}/static.#{format}"
end

.sync_wait(time, mutex) ⇒ Object

Wait a specified amount of time synchronised with the specified mutex.



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

def sync_wait(time, mutex)
  mutex.synchronize { sleep time }
end

.team_icon_url(team_id, icon_id, format = 'webp') ⇒ Object

make a team icon URL from team and icon IDs.



287
288
289
 
# File 'lib/discordrb/api.rb', line 287

def team_icon_url(team_id, icon_id, format = 'webp')
  "#{cdn_url}/team-icons/#{team_id}/#{icon_id}.#{format}"
end

.trace(reason) ⇒ Object

Perform rate limit tracing. All this method does is log the current backtrace to the console with the :ratelimit level.

Parameters:

  • reason (String) —

    the reason to include with the backtrace.



190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/discordrb/api.rb', line 190

def trace(reason)
  unless @trace
    Discordrb::LOGGER.debug("trace was called with reason #{reason}, but tracing is not enabled")
    return
  end

  Discordrb::LOGGER.ratelimit("Trace (#{reason}):")

  caller.each do |str|
    Discordrb::LOGGER.ratelimit(" #{str}")
  end
end

.trace=(value) ⇒ Object

Changes the rate limit tracing behaviour. If rate limit tracing is on, a full backtrace will be logged on every RL hit.

Parameters:

  • value (true, false) —

    whether or not to enable rate limit tracing



47
48
49
 
# File 'lib/discordrb/api.rb', line 47

def trace=(value)
  @trace = value
end

.update_oauth_application(token, name, redirect_uris, description = '', icon = nil) ⇒ Object

Deprecated.

Please use Discordrb::API::Application#update_current_application instead.

Change an OAuth application's properties



293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/discordrb/api.rb', line 293

def update_oauth_application(token, name, redirect_uris, description = '', icon = nil)
  request(
    :oauth2_applications,
    nil,
    :put,
    "#{api_base}/oauth2/applications",
    { name: name, redirect_uris: redirect_uris, description: description, icon: icon }.to_json,
    Authorization: token,
    content_type: :json
  )
end

.user_agent ⇒ Object

Generate a user agent identifying this requester as discordrb.



52
53
54
55
56
57
58
 
# File 'lib/discordrb/api.rb', line 52

def user_agent
  # This particular string is required by the Discord devs.
  required = "DiscordBot (https://github.com/shardlab/discordrb, v#{Discordrb::VERSION})"
  @bot_name ||= ''

  "#{required} rest-client/#{RestClient::VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION}p#{RUBY_PATCHLEVEL} discordrb/#{Discordrb::VERSION} #{@bot_name}"
end

.voice_regions(token) ⇒ Object

Get a list of available voice regions



340
341
342
343
344
345
346
347
348
349
 
# File 'lib/discordrb/api.rb', line 340

def voice_regions(token)
  request(
    :voice_regions,
    nil,
    :get,
    "#{api_base}/voice/regions",
    Authorization: token,
    content_type: :json
  )
end

.widget_url(server_id, style = 'shield') ⇒ Object

Make a widget picture URL from server ID



214
215
216
 
# File 'lib/discordrb/api.rb', line 214

def widget_url(server_id, style = 'shield')
  "#{api_base}/guilds/#{server_id}/widget.png?style=#{style}"
end