RestActions

RestActions

Every call to the Guilded REST API is made through a RestAction<T>. You get one from the RestClient (jg_api.getRestClient()) or from the entities themselves (message.delete(), channel.sendMessage("hi"), ...).

Creating a RestAction doesn't send anything. The request is only made once you run it in one of the three ways below.

queue() - the recommended way

The action is put on the library's queue and processed on a background thread. Results are handed to consumers:

message.delete().queue(
        deleted -> System.out.println("Deleted!"),   // success
        error -> error.printStackTrace()              // failure
);

message.reply("Pong!").queue();                      // fire and forget

• Both consumers are optional. If a queued action fails and you didn't pass a failure consumer, the error is printed to System.err.
• Queued actions are executed in the order they were created.
• Queued actions that get rate limited by Guilded are retried automatically, see Error Handling and Rate Limits.
• The queue is processed by the JG_API thread. It is started by jg_api.start(), and also automatically the first time something is queued.

Delayed

channel.sendMessage("One minute later...").queueAfter(TimeUnit.MINUTES, 1);

complete() - blocking

Executes the request immediately on the calling thread, skipping the queue, and returns the result:

try {
    ServerMember member = jg_api.getRestClient().getMember(serverId, userId).complete();
    System.out.println(member.getNickname());
} catch (IOException e) {
    // The request could not be made / no response arrived
} catch (RestActionException e) {
    // Guilded answered with an error, or the answer could not be understood
    System.out.println(e.getStatusCode() + " " + e.getErrorCode());
}

Don't call complete() inside an event handler for things that can wait, it blocks the gateway thread while waiting for the response.

submit() - asynchronous

Executes the request on another thread right away (skipping the queue) and returns a CompletableFuture<T>:

jg_api.getRestClient().getServer(serverId)
        .submit()
        .thenAccept(server -> System.out.println(server.getName()))
        .exceptionally(error -> { error.printStackTrace(); return null; });

Which one should I use?

	Goes through the queue	Blocks	Retries rate limits
queue()	yes	no	yes
complete()	no	yes	no
submit()	no	no	no

Return values

• Routes that don't return anything (deleting, pinning, ...) give a Boolean that is true on success.
• Routes that return lists give an array, e.g. RestAction<ChatMessage[]>.
• The full list of routes and what they return is on Supported Endpoints.

Timeouts

Requests time out after 20 seconds by default. Change it per action with restAction.setTimeout(milliseconds).

Throttled queue

For bots that do a lot of bulk work you can slow the queue down. In this mode only 5 actions are processed every 10 seconds:

jg_api.setQueueEnabled(true);