API Wrapper

The Discordrb::API namespace is the library's HTTP REST binding to Discord's API. The rest of the library (Discordrb::Bot, etc.) wraps all of these "lower level" HTTP functions to provide higher level, easy to use, and safe functionality.

This article explains how Discordrb::API works, when to consider using it, and its relationship with Discordrb::Bot. While this is primarily aimed at application / bot developers, it may also help those wanting to learn how to contribute to discordrb.

Should I use Discordrb::API?

All Discordrb::API functions are public, and there may be certain use cases where use of these lower level functions might be more appropriate than using a Bot. To evaluate if this is the right choice for your application, consider the following questions:

• Do you need access to large amounts of cached Discord data, like the servers, users, and channels your bot has access to?

• Do you need to respond to real time events, such as messages being sent, or when properties of a server or channel changes?

• Do you need voice features?

If the answer to all of those is "no", then you can probably use these methods instead of a Bot and avoid the overhead of holding a cache in memory when your application doesn't really need it.

If the answer to any of those is "yes", it is strongly recommended that you use a Discordrb::Bot to avoid the large amount of HTTP requests you would have to make otherwise. (Example: Polling a channel for new messages is a really bad idea)

It is also not advisable to use these methods if you are inexperienced with HTTP APIs in general, or new to Ruby.

How does it work?

Discordrb::API methods are organized by topic. There is Discordrb::API::Channel for channel methods, Discordrb::API::Server for server related methods, and so on. All of these methods, with few exceptions:

• Take your bots token as the first argument.*

• Discord rate limiting is still automatically handled

• Return a plain String of the response body, or raises an exception on a failed request

* - Your bot's token MUST be prefixed with the string "Bot ". It is case sensitive and must have the included whitespace character.

This is an example of sending a message to a channel, just using Discordrb::API:

# Creates a message in a channel. Returns the created message.
response = Discordrb::API::Channel.create_message("Bot TOKEN", 83281822225530880, "hello world!")
response #=> "{\"content\":\"hello world!\" ... }"

# Response is just a JSON string, we can parse it into a hash:
parsed = JSON.parse(response)
parsed["content"]    #=> "hello world!"
parsed["channel_id"] #=> "83281822225530880"

All of our Discordrb::API methods are documented by Discord's official documentation. You should read those docs to understand what objects you can expect to receive back from the API, and what each argument does.

Note: As of writing, Discord requires your bot to have connected and authorized with the gateway at least once in your application's lifetime before you will be able to send messages. You do not need to maintain a gateway connection after this. This is the only method this restriction applies to.

What if I only need to send messages, and nothing else?

Use Webhooks.

Can't I just use a Bot without connecting?

It depends. The methods of Discordrb::Bot are highly dependent on state. This means a lot of features require a cache and a gateway connection in order to be used. Some methods will immediately raise an exception if you try to use them without a gateway connection active (bot.run). Others may work perfectly, as some methods are just simple wrappers around the Discordrb::API methods, and others may return objects with "incomplete" fields that causes subsequent methods to fail with a pretty cryptic error. (Unless you are more intimately familiar with how Discordrb and Discord's API works)

Discordrb::Bot is not intended to be used without bot.run and the library provides no guarantee of safety if you try to use it without a gateway connection.