Guide: Anatomy of an API Route

[bitfl0wer]

Want to contribute to Chorus by implementing a missing API route, but don't know where and how to start? This forum post should cover the basics about what to write and where. I will be using the "Modify Guild" route as an example.

File Structure

When cloning chorus and looking inside the repository folder, you should see something like this:

Here's a breakdown of all the folders and files we'll be touching in this example:

Folder/Subfolder/File	Explanation
/src/api/	Holds all the API route implementations. Features subfolders like 'auth', 'channels' to organize functionality a bit better.
/src/api/guilds/guilds.rs	The file we will be placing our new API route in.
/src/types/entities/	Houses all the different entity structs, which describe, what a Guild, a Channel or a User look like.
/src/types/schema/	Describes all schemas. Schemas contain all the input fields the server wants from you when performing actions like registrating, logging in, modifying a user, etc.
/src/instance.rs	Contains the Instance and UserMeta structs, which represent the Instance and the user whose account is being puppeteered by this library respectively.
/src/ratelimiter.rs	Contains all the logic for sending requests to the API, as well as functions for processing them.

The signature of our new function

Since the new function is supposed to modify a Guild, we will be placing it inside /src/api/guilds/guilds.rs's impl Guild {...} block. The function signature will look like this:

pub async fn modify(guild_id: Snowflake, schema: GuildModifySchema, user: &mut UserMeta) -> ChorusResult<Guild> {
    ...
}

Let's break this down bit by bit.

The function is supposed to be part of the public chorus API, therefore requiring the visibility modifier pub. Network requests are sent to the server and awaited in an asynchronous manner, calling for the async fn keywords.

I personally like using Discord Userdoccers to look at Discord API Documentation, so let's take a look at what it has got to say about the Guild::modify route:

From looking at this, we can already make out the first two function arguments, our new function will require:

• The API URL of the Instance, we try to modify a Guild on. We can get the API-URL of the Instance from the User, which we will use to make the request with. This is the user: &mut UserMeta-part in the function signature.
• {guild.id} is the ID of the Guild we want to modify. In the function signature, this is our guild_id: Snowflake (since Discord IDs are always Snowflakes.)

If we scroll a bit further down the page, we'll see this:

This is the JSON body we will be sending to the server. We can see that it requires a lot of fields, which is why in the next step, we will be creating a new schema for this route. The schema will be placed inside /src/types/schema/guilds.rs and will look like this:

#[derive(Debug, Deserialize, Serialize, Default, Clone, Eq, PartialEq)]
#[serde(rename_all = "snake_case")]
pub struct GuildModifySchema {
    pub name: Option<String>,
    pub icon: Option<Vec<u8>>,
    pub banner: Option<Vec<u8>>,
    pub home_header: Option<Vec<u8>>,
    pub splash: Option<Vec<u8>>,
    pub discovery_splash: Option<Vec<u8>>,
    pub owner_id: Option<Snowflake>,
    pub description: Option<String>,
    pub region: Option<String>,
    pub afk_channel_id: Option<Snowflake>,
    pub afk_timeout: Option<u16>,
    pub verification_level: Option<VerificationLevel>,
    pub default_message_notifications: Option<MessageNotificationLevel>,
    pub explicit_content_filter: Option<ExplicitContentFilterLevel>,
    pub features: Option<Vec<GuildFeatures>>,
    pub system_channel_id: Option<Snowflake>,
    pub system_channel_flags: Option<SystemChannelFlags>,
    pub rules_channel_id: Option<Snowflake>,
    pub public_updates_channel_id: Option<Snowflake>,
    pub safety_alerts_channel_id: Option<Snowflake>,
    pub preferred_locale: Option<String>,
    pub premium_progress_bar_enabled: Option<bool>,
}

A hint on optional parameters

Hint: The documentation page sometimes (in this case, always) specifies a "?" after a field name. This means that the field is optional and can be omitted. This is why all fields in the schema are wrapped in Option<>s.

The return type

Now that we have covered all function arguments, let's look at the function return type!
The Discord Userdoccers state:

...Returns the updated guild object on success.

In Chorus/the Discord API, we generally only encounter two different return types:

ChorusResult<..., E>

• ChorusResult<()>: This is the return type for all routes that don't return anything. The () is the Rust equivalent of void in C++. The ChorusResult is a type alias for Result<(), ChorusError>, which is a Result that either returns Ok(()) (so - nothing) or Err(ChorusError), in case something went wrong.
• ChorusResult<T>, where T is an entity: This is the return type for all routes that return something. ChorusResult<...> means the same thing as it does in the previous example, but instead of () we have a generic type T, which is an entity. In this case, the function will return Ok(T) if everything went well, or Err(ChorusError) if something went wrong.

In the case of our modify function, we will be returning ChorusResult<Guild>, since we expect the server to return the updated Guild object.

And there we have it! The function signature is complete. Now, let's take a look at the function body.

The function body

Let's take a look at, and then dissect the function body:

pub async fn modify(
        guild_id: Snowflake,
        schema: GuildModifySchema,
        user: &mut UserMeta,
    ) -> ChorusResult<Guild> {
        let chorus_request = ChorusRequest {
            request: Client::new()
                .patch(format!(
                    "{}/guilds/{}",
                    user.belongs_to.borrow().urls.api,
                    guild_id,
                ))
                .header("Authorization", user.token())
                .body(to_string(&schema).unwrap()),
            limit_type: LimitType::Guild(guild_id),
        };
        let response = chorus_request.deserialize_response::<Guild>(user).await?;
        Ok(response)
    }

ChorusRequest

The first thing we do is create a new ChorusRequest. The ChorusRequest is a struct that contains all the information needed to send a request to the server. It contains the request itself, as well as the LimitType of the request. The LimitType is an enum that describes the type of request we are sending and is important to tell Chorus' ratelimiter what sort of Request it is dealing with. In this case, we are sending a request to modify a Guild, so we will be using LimitType::Guild(guild_id). The guild_id is the ID of the Guild we are modifying.

The ChorusRequest takes two arguments:

• The request itself. This is a reqwest::RequestBuilder.
• The LimitType of the request.

Making the RequestBuilder

If reqwest::Client is imported via a use statement, creating a new RequestBuilder is as easy as calling Client::new().<method>(<url>). In this case, we are using the patch method, since we are sending a PATCH request to the server (Discord Userdoccers tell us this information). The URL is the API URL of the Instance we are sending the request to, plus the endpoint we are sending the request to. In this case, we are sending a PATCH request to https://api.polyphony.rocks/guilds/<guild_id>, so we are using format!("{}/guilds/{}", user.belongs_to.borrow().urls.api, guild_id) to create the URL.

Hint: I recommend reading the reqwest::Client documentation to learn more about the different methods and how to use them.

Adding the Authorization Header

The next thing we do is add the Authorization header to the request. This is done by calling .header("Authorization", user.token()) on the RequestBuilder. The user.token() method returns the token of the user, which is used to authenticate the request. Discord and Spacebar need this token to know which user is sending the request.

Adding the JSON body

Let's add the JSON body to the request, so that the Server can actually know what our user wants to modify about the guild. This is done by calling .body(serde_json::to_string(&schema).unwrap()) on the RequestBuilder. The to_string(&schema) method serializes the schema into a JSON string, which is then added to the request. The .unwrap() is needed to unwrap the Result returned by to_string(&schema), since the body method only accepts Strings, not Result<String, serde_json::Error>s. Note that calling serde_json::to_string() is only possible, if you annotated the schema (in this case: GuildModifySchema)with #[derive(Serialize)].

Adding the LimitType

The last thing we do is add the LimitType to the ChorusRequest. Just type LimitType:: into your IDE and let the autocomplete suggestions handle the rest. Note, that you will have to add the guild_id as an argument to the LimitType::Guild variant.

Great! We now have the ChorusRequest and can send it to the server. But how do we do that?

Sending the request and handling the response

We have previously talked about the two different return types of Chorus/Discord API endpoints. Luckily for you, Chorus has functions that handles both of them for you: ChorusRequest::deserialize_response::<T>(user: &mut UserMeta), if you expect a response of type T, and ChorusRequest::handle_request_as_result(user: &mut UserMeta) if you expect no meaningful answer from the server.

In this case, we will be using the deserialize_response function, since we expect the server to return the updated Guild object. The deserialize_response function takes one argument: A mutable reference to the UserMeta struct. This is needed for all the fancy logic which is involved in sending requests to the server. The deserialize_response function needs to know the type of the response, so it can deserialize the response into the correct type. In this case, we are expecting a Guild object, so we will be using deserialize_response::<Guild>(user).

Hint: Don't forget to .await the function call! :P

The deserialize_response function returns a ChorusResult<Guild>, which is the same as Result<Guild, ChorusError>. This means that we can use the ? operator to return the Guild object if everything went well, or return the ChorusError if something went wrong. This is done by just adding a ? after the function call.

The last thing we do is wrap the Guild object in an Ok() and return it. This is done by calling Ok(response).

Yay

Congratulations! You have successfully implemented a new API route! You should now take a look at how to test it, and then submit a pull request to the Chorus repository. If you have any questions, feel free to ask them in the #chorus-discussion channel on the Polyphony Discord server. We will be happy to help you out. :)